Framework | Security.framework |
Declared in | CMSDecoder.h CMSEncoder.h |
Cryptographic Message Syntax Services is an API that implements Cryptographic Message Syntax (CMS) digital signatures and encryption for S/MIME messages.
A CMS message can be signed, encrypted, or both. A message can be signed by an arbitrary number of signers and can be encrypted for an arbitrary number of recipients. In CMS terminology, this module performs encryption using the enveloped-data content type and signing using the signed-data content type.
If the message is both signed and encrypted, it uses nested ContentInfo types in CMS terminology. In this case, the enveloped data content contains the signed data content; that is, the message is first signed and then the signed content is encrypted.
Cryptographic Message Syntax is defined in RFC 3852: Cryptographic Message Syntax (CMS) (http://www.ietf.org/rfc/rfc3852.txt).
S/MIME is defined in RFC 3851: Secure/Multipurpose Internet Mail Extensions (S/MIME) Version 3.1 Message Specification (http://www.ietf.org/rfc/rfc3851.txt)
CMSEncoderAddSigners
CMSEncoderCopySigners
CMSEncoderAddRecipients
CMSEncoderCopyRecipients
CMSEncoderSetHasDetachedContent
CMSEncoderGetHasDetachedContent
CMSEncoderSetEncapsulatedContentType
CMSEncoderCopyEncapsulatedContentType
CMSEncoderAddSupportingCerts
CMSEncoderCopySupportingCerts
CMSEncoderAddSignedAttributes
CMSEncoderSetCertificateChainMode
CMSEncoderGetCertificateChainMode
CMSDecoderUpdateMessage
CMSDecoderFinalizeMessage
CMSDecoderSetDetachedContent
CMSDecoderCopyDetachedContent
CMSDecoderSetSearchKeychain
CMSDecoderGetNumSigners
CMSDecoderCopySignerStatus
CMSDecoderCopySignerEmailAddress
CMSDecoderCopySignerCert
CMSDecoderIsContentEncrypted
CMSDecoderCopyEncapsulatedContentType
CMSDecoderCopyAllCerts
CMSDecoderCopyContent
Obtain an array of all of the certificates in a message.
OSStatus CMSDecoderCopyAllCerts( CMSDecoderRef cmsDecoder, CFArrayRef *certsOut );
The CMSDecoder reference returned by the CMSDecoderCreate
function.
On return, points to an array of SecCertificateRef
objects. Returns NULL
if the message does not contain any certificates (the message was encrypted but not signed); this is not considered an error. You must use the CFRelease
function to free this reference when you are finished using it.
A result code. See “Cryptographic Message Services Result Codes.”
A CMS message can contain arbitrary sets of certificates other than or in addition to those indicating the identity of signers. You can use this function to retrieve such certificates from a message. If the message was signed, it contains signer certificates. You can use the CMSDecoderGetNumSigners
and CMSDecoderCopySignerCert
functions to retrieve the certificates for a specific signer.
You cannot call this function until after you have called the CMSDecoderFinalizeMessage
function.
CMSDecoderCreate
CMSDecoderFinalizeMessage
CMSEncoderAddSupportingCerts
CMSDecoderGetNumSigners
CMSDecoderCopySignerCert
CMSDecoder.h
Obtain the message content, if any.
OSStatus CMSDecoderCopyContent( CMSDecoderRef cmsDecoder, CFDataRef *contentOut );
The CMSDecoder reference returned by the CMSDecoderCreate
function.
On return, points to the message’s content. Returns NULL
if the content is detached. You must use the CFRelease
function to free this reference when you are finished using it.
A result code. See “Cryptographic Message Services Result Codes.”
If the message has detached content, you are responsible for retrieving the content. In that case, you use the CMSDecoderSetDetachedContent
function to tell the decoder the location of the content.
You cannot call this function until after you have called the CMSDecoderFinalizeMessage
function.
CMSDecoderCreate
CMSDecoderSetDetachedContent
CMSEncoderSetHasDetachedContent
CMSDecoderFinalizeMessage
CMSDecoder.h
Obtains the detached content specified with the CMSDecoderSetDetachedContent
function.
OSStatus CMSDecoderCopyDetachedContent( CMSDecoderRef cmsDecoder, CFDataRef *detachedContentOut );
The CMSDecoder reference returned by the CMSDecoderCreate
function.
On return, points to the data reference specified by an earlier call to the CMSDecoderSetDetachedContent
function. Returns a NULL data reference if no detached content has been specified. You must use the CFRelease
function to free this reference when you are finished using it.
A result code. See “Cryptographic Message Services Result Codes.”
CMSDecoder.h
Obtains the object identifier for the encapsulated data of a signed message.
OSStatus CMSDecoderCopyEncapsulatedContentType( CMSDecoderRef cmsDecoder, CFDataRef *eContentTypeOut );
The CMSDecoder reference returned by the CMSDecoderCreate
function.
On return, the object identifier for the encapsulated data in a signed message. Returns NULL
if the message was not signed.
A result code. See “Cryptographic Message Services Result Codes.”
In a signed message, the signed data consists of any type of content (referred to as the encapsulated content, because it is encapsulated in the signed data) plus the signature values. The content type of the encapsulated data is indicated by an object identifier. The default value for the OID is id-data
, which indicates MIME-encoded content.
You cannot call this function until after you have called the CMSDecoderFinalizeMessage
function.
CMSDecoder.h
Obtains the certificate of the specified signer of a CMS message.
OSStatus CMSDecoderCopySignerCert( CMSDecoderRef cmsDecoder, size_t signerIndex, SecCertificateRef *signerCertOut );
The CMSDecoder reference returned by the CMSDecoderCreate
function.
A number indicating which signer’s email address to return. Signer index numbers start with 0. Use the CMSDecoderGetNumSigners
function to determine the total number of signers for a message.
On return, points to the certificate of the specified signer.
A result code. See “Cryptographic Message Services Result Codes.” Returns paramErr
(–50) if the CMS message was not signed or if signerIndex
is greater than the number of signers of the message minus one (signerIndex > (numSigners – 1)).
You cannot call this function until after you have called the CMSDecoderFinalizeMessage
function.
CMSDecoder.h
Obtains the email address of the specified signer of a CMS message.
OSStatus CMSDecoderCopySignerEmailAddress( CMSDecoderRef cmsDecoder, size_t signerIndex, CFStringRef *signerEmailAddressOut );
The CMSDecoder reference returned by the CMSDecoderCreate
function.
A number indicating which signer’s email address to return. Signer index numbers start with 0. Use the CMSDecoderGetNumSigners
function to determine the total number of signers for a message.
On return, points to the email address of the specified signer.
A result code. See “Cryptographic Message Services Result Codes.” Returns paramErr
(–50) if the CMS message was not signed or if signerIndex
is greater than the number of signers of the message minus one (signerIndex > (numSigners – 1)
).
You cannot call this function until after you have called the CMSDecoderFinalizeMessage
function.
CMSDecoder.h
Obtains the status of a CMS message's signature.
OSStatus CMSDecoderCopySignerStatus( CMSDecoderRef cmsDecoder, size_t signerIndex, CFTypeRef policyOrArray, Boolean evaluateSecTrust, CMSSignerStatus *signerStatusOut, SecTrustRef *secTrustOut, OSStatus *certVerifyResultCodeOut );
The CMSDecoder reference returned by the CMSDecoderCreate
function.
A number indicating which signer to examine. Signer index numbers start with 0. Use the CMSDecoderGetNumSigners
function to determine the total number of signers for a message.
The trust policy or policies to be used to verify the signer’s certificate. You can specify either a single SecPolicyRef
object or a CFArray
of SecPolicyRef
objects. Trust policies are discussed in Certificate, Key, and Trust Services Concepts in Certificate, Key, and Trust Services Programming Guide.
Set to TRUE
to cause the decoder to call the SecTrustEvaluate
function to evaluate the SecTrust
object created for the evaluation of the signer certificate. Set to FALSE
if you intend to call the SecTrustEvaluate
function for the SecTrust
object returned by the secTrustOut
parameter.
If you specify TRUE
for the evaluateSecTrust
parameter, on return this parameter indicates the status of the signature. See “Signature Status Constants” for possible results. Pass in NULL
if you don’t want a value returned.
On return this parameter points to a SecTrust
object. If you specified TRUE
for the evaluateTrust
parameter, this is the trust object that was used to verify the signer's certificate. If you specified FALSE
for the evaluateTrust
parameter, you can call the SecTrustEvaluate
function to evaluate the SecTrust
object. Pass NULL
if you do not want this object returned. You must use the CFRelease
function to free this reference when you are finished using it.
If you specify TRUE
for the evaluateSecTrust
parameter, on return this parameter indicates the result of the certificate verification. Pass in NULL
if you don’t want a value returned.
Some of the most common results returned in this parameter include:
CSSMERR_TP_INVALID_ANCHOR_CERT
The certificate was verified through the certificate chain to a self-signed root certificate that was present in the message, but that root certificate is not a known, trusted root certificate.
CSSMERR_TP_NOT_TRUSTED
The certificate could not be verified back to a root certificate.
CSSMERR_TP_VERIFICATION_FAILURE
The root certificate failed verification.
CSSMERR_TP_VERIFY_ACTION_FAILED
Trust could not be established according to the specified trust policy.
CSSMERR_TP_INVALID_CERTIFICATE
The signer’s leaf certificate was not valid.
CSSMERR_TP_CERT_EXPIRED
A certificate in the chain was expired at the time of verification.
CSSMERR_TP_CERT_NOT_VALID_YET
A certificate in the chain was not yet valid at the time of verification.
A result code. See “Cryptographic Message Services Result Codes.” A result of noErr
indicates only that the function completed successfully; it does not indicate that the signature is verified or the certificates are valid. See the signerStatusOut
and certVerifyResultCodeOut
parameters for the verification and certificate validation results.
You cannot call this function until after you have called the CMSDecoderFinalizeMessage
function. Although the message has been fully decoded when the CMSDecoderFinalizeMessage
function returns with no error, the signature can’t be validated or certificates verified until this function is called.
A CMS message can be signed by multiple signers; this function returns the status associated with one signer as specified by the signerIndex
parameter.
If you both pass in FALSE
for the evaluateSecTrust
parameter and NULL
for the secTrustOut
parameter, no evaluation of the signer certificate can occur.
CMSDecoder.h
Creates a CMSDecoder.
OSStatus CMSDecoderCreate( CMSDecoderRef *cmsDecoderOut );
On return, points to a CMSDecoder reference. You must use the CFRelease
function to free this reference when you are finished using it.
A result code. See “Cryptographic Message Services Result Codes.”
This is the first function in a sequence of decoder functions that you call to get information from a CMS message. The other functions in the sequence require you to pass in the CMSDecoder reference returned by this function. The next function in the sequence is CMSDecoderUpdateMessage
.
CMSDecoder.h
Indicates that there is no more data to decode.
OSStatus CMSDecoderFinalizeMessage( CMSDecoderRef cmsDecoder );
The CMSDecoder reference returned by the CMSDecoderCreate
function.
A result code. Returns errSecUnknownFormat
upon detection of an improperly formatted CMS message. See “Cryptographic Message Services Result Codes” for other result codes.
When you call this function, the decoder finishes decoding the message. If the message was encrypted and this function returns a result code of noErr
, the message was successfully decrypted. Call the CMSDecoderCopyContent
function to retrieve the message content. Call the CMSDecoderGetNumSigners
function to find out if the message was signed and, if so, how many signers there were.
CMSDecoder.h
Obtains the number of signers of a message.
OSStatus CMSDecoderGetNumSigners( CMSDecoderRef cmsDecoder, size_t *numSignersOut );
The CMSDecoder reference returned by the CMSDecoderCreate
function.
On return, the number of signers of the message. Zero indicates that the message was not signed.
A result code. See “Cryptographic Message Services Result Codes.”
Call the CMSDecoderCopySignerStatus
function to determine the status of a signature.
You cannot call this function until after you have called the CMSDecoderFinalizeMessage
function.
CMSDecoder.h
Returns the type identifier for the CMSDecoder opaque type.
CFTypeID CMSDecoderGetTypeID(void);
CMSDecoder.h
Determines whether a CMS message was encrypted.
OSStatus CMSDecoderIsContentEncrypted( CMSDecoderRef cmsDecoder, Boolean *isEncryptedOut );
The CMSDecoder reference returned by the CMSDecoderCreate
function.
Returns TRUE
if the message was encrypted.
A result code. See “Cryptographic Message Services Result Codes.”
Note that if the message was encrypted and the decoding succeeded (CMSDecoderFinalizeMessage
returned noErr
), then the message was successfully decrypted. Call CMSDecoderCopyContent
to retrieve the decrypted content.
You cannot call this function until after you have called the CMSDecoderFinalizeMessage
function.
CMSDecoder.h
Specifies the message’s detached content, if any.
OSStatus CMSDecoderSetDetachedContent( CMSDecoderRef cmsDecoder, CFDataRef detachedContent );
The CMSDecoder reference returned by the CMSDecoderCreate
function.
A reference to the message’s detached content.
A result code. See “Cryptographic Message Services Result Codes.”
The data of a signed CMS message can optionally be sent separately from the message. If the message’s content is detached from the message, you must call this function to tell the decoder where to find the message content.
Encrypted messages, including those that are also signed, cannot use detached content.
You can call this function either before or after decoding the message (by calling the CMSDecoderUpdateMessage
and CMSDecoderFinalizeMessage
functions). If a signed message has detached content, however, you must call this function before you can use the CMSDecoderCopySignerStatus
function to ascertain the signature status.
CMSDecoderCreate
CMSDecoderUpdateMessage
CMSDecoderFinalizeMessage
CMSDecoderCopySignerStatus
CMSDecoderCopyDetachedContent
CMSEncoderSetHasDetachedContent
CMSDecoder.h
Specifies the keychains to search for intermediate certificates to be used in verifying a signed message's signer certificates.
OSStatus CMSDecoderSetSearchKeychain( CMSDecoderRef cmsDecoder, CFTypeRef keychainOrArray );
The CMSDecoder reference returned by the CMSDecoderCreate
function.
Either a single keychain to search, specified as a keychain object (type SecKeychainRef
), or a set of keychains specified as a CFArray
of keychain objects. If you specify an empty CFArrayRef
, no keychains are searched for intermediate certificates.
A result code. See “Cryptographic Message Services Result Codes.”
If you don’t call this function, the decoder uses the default keychain search list to search for intermediate certificates.
If you do call this function, you must call it before you call the CMSDecoderCopySignerStatus
function.
CMSDecoder.h
Feeds raw bytes of the message to be decoded into the decoder.
OSStatus CMSDecoderUpdateMessage( CMSDecoderRef cmsDecoder, const void *msgBytes, size_t msgBytesLen );
The CMSDecoder reference returned by the CMSDecoderCreate
function.
A pointer to the data to be decoded.
The length of the data, in bytes.
A result code. Returns errSecUnknownFormat
upon detection of an improperly formatted CMS message. See “Cryptographic Message Services Result Codes” for other result codes.
This function can be called multiple times. Call the CMSDecoderFinalizeMessage
function when you have no more data to decode.
CMSDecoder.h
Encodes a message and obtains the result in one high-level function call.
OSStatus CMSEncode( CFTypeRef signers, CFTypeRef recipients, const CSSM_OID *eContentType, Boolean detachedContent, CMSSignedAttributes signedAttributes, const void *content, size_t contentLen, CFDataRef *encodedContentOut );
The identity object for the identity of one signer, specified as type SecIdentityRef
, or a CFArray
of identity objects of typeSecIdentityRef
. Pass NULL
for this parameter if you do not want to sign the message.
A certificate containing a public encryption key for one message recipient, specified as a certificate object (type SecCertificateRef
), or a CFArray
of certificate objects. Pass NULL for this parameter if you do not want to encrypt the message.
The object identifier for the encapsulated data in a signed message. This parameter is optional. If you pass 0
, the value id-data
is used. (This is the normal encapsulated content type for applications such as S/MIME, which uses it to indicate MIME-encoded content.) You can pass any value that is meaningful to your application.
Specify TRUE
if the signed data is to be separate from the message; that is, if the message isnot to include the data to be signed. You cannot specify TRUE
for this parameter for an encrypted message.
Attribute flags as defined in “Attributes For Signed Messages.” Attributes are optional for signed messages and are not used in other types of CMS messages. The use of attributes is described in section 2.5 of the S/MIME 3.1 specification.
The content that you want to add to the message. The content must conform to the type set in the CMSEncoderSetEncapsulatedContentType
parameter (or type id-data
if that function has not been called).
The length of the content being added, in bytes.
On return, points to the encoded message. You must use the CFRelease
function to free this reference when you are finished using it.
A result code. See “Cryptographic Message Services Result Codes.”
If you use this function, you must include content and you must provide valid non-NULL
input for at least one of the signers
and recipients
parameters. You can both encrypt and sign a message; however, you cannot use detached content with an encrypted message. If you want to create a message that contains certificates and no other content, you must use the CMSEncoderAddSupportingCerts
function instead of this one. To gain more control over the process of encoding a message, call the sequence of functions beginning with the CMSEncoderCreate
function instead of this one.
CMSEncoder.h
Specifies a message is to be encrypted and specifies the recipients of the message.
OSStatus CMSEncoderAddRecipients( CMSEncoderRef cmsEncoder, CFTypeRef recipientOrArray );
The CMSEncoder reference returned by the CMSEncoderCreate
function.
Either a single certificate containing a public encryption key for one message recipient, specified as a certificate object (type SecCertificateRef
), or a set of certificates specified as a CFArray
of certificate objects.
A result code. See “Cryptographic Message Services Result Codes.”
Your keychain must contain a certificate that supports encryption for each recipient. You can call this function more than once for the same message.
You can both sign and encrypt the same message; however, you cannot call both this function and the CMSEncoderSetHasDetachedContent
function for the same message.
If you do call this function, you must call it before the first call to the CMSEncoderUpdateContent
function.
CMSEncoderCreate
CMSEncoderSetHasDetachedContent
CMSEncoderUpdateContent
CMSEncoderCopyRecipients
CMSDecoderIsContentEncrypted
CMSEncoder.h
Specifies attributes for a signed message.
OSStatus CMSEncoderAddSignedAttributes( CMSEncoderRef cmsEncoder, CMSSignedAttributes signedAttributes );
The CMSEncoder reference returned by the CMSEncoderCreate
function.
Attribute flags as defined in “Attributes For Signed Messages.”
A result code. See “Cryptographic Message Services Result Codes.”
Attributes are optional for signed messages. They are not used for other types of CMS messages. The use of attributes is described in section 2.5 of the S/MIME 3.1 specification.
If you do call this function, you must call it before the first call to the CMSEncoderUpdateContent
function.
CMSEncoder.h
Specifies signers of the message.
OSStatus CMSEncoderAddSigners( CMSEncoderRef cmsEncoder, CFTypeRef signerOrArray );
The CMSEncoder reference returned by the CMSEncoderCreate
function.
The identity object for the identity of one signer, specified as type SecIdentityRef
, or a CFArray
of identity objects of typeSecIdentityRef
.
A result code. See “Cryptographic Message Services Result Codes.”
Call this function only if the message is to be signed. You can call this function more than once for the same message.
If you do call this function, you must call it before the first call to the CMSEncoderUpdateContent
function.
CMSEncoder.h
Adds certificates to a message.
OSStatus CMSEncoderAddSupportingCerts( CMSEncoderRef cmsEncoder, CFTypeRef certOrArray );
The CMSEncoder reference returned by the CMSEncoderCreate
function.
Either a single certificate, specified as a certificate object (type SecCertificateRef
), or a set of certificates specified as a CFArray
of certificate objects.
A result code. See “Cryptographic Message Services Result Codes.”
A CMS message can contain arbitrary sets of certificates other than or in addition to those indicating the identity of signers. You can use this function to add such certificates to a message. It is not necessary to call this function for a normal signed message. When you create a signed message, Cryptographic Message Services automatically adds the signer certificates and any intermediate certificates needed to verify the signers.
You can use this function even if you don’t sign or encrypt the message, in order to transport one or more certificates. To do so, call CMSEncoderCreate
to obtain a CMSEncoderRef
reference, call CMSEncoderAddSupportingCerts
one or more times, and then call CMSEncoderCopyEncodedContent
to complete the message. No additional content need be specified.
If you do add content to the message in addition to the certificates, you must call this function before the first call to the CMSEncoderUpdateContent
function.
CMSEncoderCreate
CMSEncoderCopyEncodedContent
CMSEncoderUpdateContent
CMSEncoderCopySupportingCerts
CMSDecoderCopyAllCerts
CMSEncoder.h
Obtains the object identifier for the encapsulated data of a signed message.
OSStatus CMSEncoderCopyEncapsulatedContentType( CMSEncoderRef cmsEncoder, CFDataRef *eContentTypeOut );
The CMSEncoder reference returned by the CMSEncoderCreate
function.
On return, points to the object identifier for the encapsulated data in the signed message.
A result code. See “Cryptographic Message Services Result Codes.”
In a signed message, the signed data consists of any type of data (the encapsulated content) plus the signature values. This function returns the object identifier (OID) of the encapsulated content as it was specified with the CMSEncoderSetEncapsulatedContentType
function.
If the CMSEncoderSetEncapsulatedContentType
function has not been called for this message, this function returns a NULL
pointer.
CMSEncoder.h
Finishes encoding the message and obtains the encoded result.
OSStatus CMSEncoderCopyEncodedContent( CMSEncoderRef cmsEncoder, CFDataRef *encodedContentOut );
The CMSEncoder reference returned by the CMSEncoderCreate
function.
On return, points to the encoded message. You must use the CFRelease
function to free this reference when you are finished using it.
A result code. See “Cryptographic Message Services Result Codes.”
This is the last function in the sequence of encoding functions you call when creating a signed or encrypted message. In many cases, you can call the CMSEncode
function alone instead of using the sequence of encoding functions.
CMSEncoder.h
Obtains the array of recipients specified with the CMSEncoderAddRecipients
function.
OSStatus CMSEncoderCopyRecipients( CMSEncoderRef cmsEncoder, CFArrayRef *recipientsOut );
The CMSEncoder reference returned by the CMSEncoderCreate
function.
On return, points to an array of certificate objects of type SecCertificateRef
of the recipients of the message. If the CMSEncoderAddRecipients
function has not been called for this message, this function returns a NULL
array. You must use the CFRelease
function to free this reference when you are finished using it.
A result code. See “Cryptographic Message Services Result Codes.”
CMSEncoder.h
Obtains the array of signers specified with the CMSEncoderAddSigners
function.
OSStatus CMSEncoderCopySigners( CMSEncoderRef cmsEncoder, CFArrayRef *signersOut );
The CMSEncoder reference returned by the CMSEncoderCreate
function.
On return, points to an array of identity objects of type SecIdentityRef
of the signers of the message. If the CMSEncoderAddSigners
function has not been called for this message, this function returns a NULL
array. You must use the CFRelease
function to free this reference when you are finished using it.
A result code. See “Cryptographic Message Services Result Codes.”
CMSEncoder.h
Obtains the certificates added to a message with CMSEncoderAddSupportingCerts
.
OSStatus CMSEncoderCopySupportingCerts( CMSEncoderRef cmsEncoder, CFArrayRef *certsOut );
The CMSEncoder reference returned by the CMSEncoderCreate
function.
On return, points to a CFArray of SecCertificateRef
objects. You must use the CFRelease
function to free this reference when you are finished using it.
A result code. See “Cryptographic Message Services Result Codes.”
A CMS message can contain arbitrary sets of certificates other than or in addition to those indicating the identity of signers. You can use this function to obtain any such certificates added with the CMSEncoderAddSupportingCerts
function. If CMSEncoderAddSupportingCerts
has not been called, this function returns a NULL
value for certsOut
. Note that this function does not return the signing certificates, if any.
CMSEncoder.h
Creates a CMSEncoder reference.
OSStatus CMSEncoderCreate( CMSEncoderRef *cmsEncoderOut );
On return, points to a CMSEncoder reference. You must use the CFRelease
function to free this reference when you are finished using it.
A result code. See “Cryptographic Message Services Result Codes.”
This is the first function in a sequence of encoder functions that you call to sign or encrypt a message. The other functions in the sequence require you to pass in the CMSEncoder reference returned by this function. In many cases, you can call the CMSEncode
function alone instead of this sequence of encoder functions.
CMSEncoder.h
Obtains a constant that indicates which certificates are to be included in a signed CMS message.
OSStatus CMSEncoderGetCertificateChainMode( CMSEncoderRef cmsEncoder, CMSCertificateChainMode *chainModeOut );
The CMSEncoder reference returned by the CMSEncoderCreate
function.
On return, a constant that indicates which certificate or certificates are to be included in the message. See “Certificate Inclusion Constants.”
A result code. See “Cryptographic Message Services Result Codes.”
CMSEncoder.h
Indicates whether the message is to have detached content.
OSStatus CMSEncoderGetHasDetachedContent( CMSEncoderRef cmsEncoder, Boolean *detachedContentOut );
The CMSEncoder reference returned by the CMSEncoderCreate
function.
Returns TRUE
if the message has detached content.
A result code. See “Cryptographic Message Services Result Codes.”
This function returns the value specified in CMSEncoderSetHasDetachedContent
if that function has been called; otherwise it returns FALSE
.
CMSEncoder.h
Returns the type identifier for the CMSEncoder opaque type.
CFTypeID CMSEncoderGetTypeID(void);
CMSEncoder.h
Specifies which certificates to include in a signed CMS message.
OSStatus CMSEncoderSetCertificateChainMode( CMSEncoderRef cmsEncoder, CMSCertificateChainMode chainMode );
The CMSEncoder reference returned by the CMSEncoderCreate
function.
A constant that indicates which certificate or certificates to include in the message. See “Certificate Inclusion Constants.”
A result code. See “Cryptographic Message Services Result Codes.”
This function is used only for signed messages and is optional. If you don’t call this function, the default, kCMSCertificateChain
, is used. In this case the message includes the signer certificate plus all certificates needed to verify the signer certificate, up to but not including the root certificate.
If you do call this function, you must call it before the first call to the CMSEncoderUpdateContent
function.
CMSEncoder.h
Specifies an object identifier for the encapsulated data of a signed message.
OSStatus CMSEncoderSetEncapsulatedContentType( CMSEncoderRef cmsEncoder, const CSSM_OID *eContentType );
The CMSEncoder reference returned by the CMSEncoderCreate
function.
The object identifier for the encapsulated data in a signed message.
A result code. See “Cryptographic Message Services Result Codes.”
In a signed message, the signed data consists of any type of content (referred to as the encapsulated content, because it is encapsulated in the signed data) plus the signature values. You can indicate the content type of the encapsulated data by specifying an object identifier (OID) in the eContentType
parameter of this function. The default value for the OID (used if this function is not called) is id-data
. This is the normal encapsulated content type for applications such as S/MIME, which uses it to indicate MIME-encoded content. You can pass any value that is meaningful to your application. Examples of CMS OIDs are listed in http://www.imc.org/ietf-smime/other-smime-oids.asn.
If you do call this function, you must call it before the first call to the CMSEncoderUpdateContent
function.
CMSEncoderCreate
CMSEncoderUpdateContent
CMSEncoderCopyEncapsulatedContentType
CMSDecoderCopyEncapsulatedContentType
CMSEncoder.h
Specifies whether the signed data is to be separate from the message.
OSStatus CMSEncoderSetHasDetachedContent( CMSEncoderRef cmsEncoder, Boolean detachedContent );
The CMSEncoder reference returned by the CMSEncoderCreate
function.
Specify TRUE
if the signed data is to be separate from the message; that is, if the message isnot to include the data to be signed.
A result code. See “Cryptographic Message Services Result Codes.”
A signed CMS message can optionally be sent separately from the signed data. The default, if this function is not called, is detachedContent=FALSE
; that is, the message contains the data to be signed.
Encrypted messages, including those that are also signed, cannot use detached content.
If you do call this function, you must call it before the first call to the CMSEncoderUpdateContent
function.
CMSEncoderCreate
CMSEncoderUpdateContent
CMSEncoderGetHasDetachedContent
CMSDecoderSetDetachedContent
CMSEncoder.h
Feeds content bytes into the encoder.
OSStatus CMSEncoderUpdateContent( CMSEncoderRef cmsEncoder, const void *content, size_t contentLen );
The CMSEncoder reference returned by the CMSEncoderCreate
function.
The content that you want to add to the message. The content must conform to the type set with the CMSEncoderSetEncapsulatedContentType
function (or type id-data
if that function has not been called).
The length of the content being added, in bytes.
A result code. See “Cryptographic Message Services Result Codes.”
You use this function to add the content that is to be signed or encrypted. If the message is only a container for certificates added with the CMSEncoderAddSupportingCerts
function and has no other content, do not call this function. This function can be called multiple times.
After you are finished adding content, call the CMSEncoderCopyEncodedContent
function to complete the message creation process.
None of the setter functions (CMSEncoderSetHasDetachedContent
, CMSEncoderSetEncapsulatedContentType
, or CMSEncoderSetCertificateChainMode
) can be called after this function has been called.
CMSEncoderCreate
CMSEncoderSetEncapsulatedContentType
CMSEncoderAddSupportingCerts
CMSEncoderCopyEncodedContent
CMSEncoder.h
Opaque reference to a CMS encoder object.
typedef struct _CMSEncoder *CMSEncoderRef;
This is object is compatible with Core Foundation and uses standard Core Foundation semantics. Dispose of it with the CFRelease
function.
CMSEncoder.h
Opaque reference to a CMS decoder object.
typedef struct _CMSDecoder *CMSDecoderRef;
This is object is compatible with Core Foundation and uses standard Core Foundation semantics. Dispose of it with the CFRelease
function.
CMSDecoder.h
Optional attributes that can be specified with the CMSEncoderAddSignedAttributes
function.
enum { kCMSAttrNone = 0x0000, kCMSAttrSmimeCapabilities = 0x0001, kCMSAttrSmimeEncryptionKeyPrefs = 0x0002, kCMSAttrSmimeMSEncryptionKeyPrefs = 0x0004, kCMSAttrSigningTime = 0x0008 }; typedef uint32_t CMSSignedAttributes;
kCMSAttrNone
No attributes.
Available in Mac OS X v10.5 and later.
Declared in CMSEncoder.h
.
kCMSAttrSmimeCapabilities
Adds information to the signed message that identifies signature, encryption, and digest algorithms supported by the encoder. Adding this attribute does not change the way in which the message is encoded. See RFC 2311: S/MIME Version 2 Message Specification (http://www.ietf.org/rfc/rfc2311.txt) section 2.5.2 for more information about the capabilities attribute.
Available in Mac OS X v10.5 and later.
Declared in CMSEncoder.h
.
kCMSAttrSmimeEncryptionKeyPrefs
Indicates that the signing certificate included with the message is the preferred one for S/MIME encryption.
Available in Mac OS X v10.5 and later.
Declared in CMSEncoder.h
.
kCMSAttrSmimeMSEncryptionKeyPrefs
Same as kCMSSmimeEncryptionKeyPrefs
, using an attribute object identifier (OID) preferred by Microsoft.
Available in Mac OS X v10.5 and later.
Declared in CMSEncoder.h
.
kCMSAttrSigningTime
Causes the encoder to include the signing time.
Available in Mac OS X v10.5 and later.
Declared in CMSEncoder.h
.
These flags cause the encoder to add attributes to a signed message that can be interpreted by the recipient. These attributes are not used for unsigned messages.
CMSEncoder.h
Constants that can be set by the CMSEncoderSetCertificateChainMode
function to specify what certificates to include in a signed message.
enum { kCMSCertificateNone = 0, kCMSCertificateSignerOnly, kCMSCertificateChain, kCMSCertificateChainWithRoot }; typedef uint32_t CMSCertificateChainMode;
kCMSCertificateNone
Don't include any certificates.
Available in Mac OS X v10.5 and later.
Declared in CMSEncoder.h
.
kCMSCertificateSignerOnly
Only include signer certificates.
Available in Mac OS X v10.5 and later.
Declared in CMSEncoder.h
.
kCMSCertificateChain
Include the signer certificate chain up to but not including the root certificate.
Available in Mac OS X v10.5 and later.
Declared in CMSEncoder.h
.
kCMSCertificateChainWithRoot
Include the entire signer certificate chain, including the root certificate.
Available in Mac OS X v10.5 and later.
Declared in CMSEncoder.h
.
CMSEncoder.h
Constants that indicate the status of the signature and signer information in a signed message, as obtained by the CMSDecoderCopySignerStatus
function.
enum { kCMSSignerUnsigned = 0, kCMSSignerValid, kCMSSignerNeedsDetachedContent, kCMSSignerInvalidSignature, kCMSSignerInvalidCert, kCMSSignerInvalidIndex }; typedef uint32_t CMSSignerStatus;
kCMSSignerUnsigned
The message was not signed.
Available in Mac OS X v10.5 and later.
Declared in CMSDecoder.h
.
kCMSSignerValid
The message was signed and both the signature and the signer certificate have been verified.
Available in Mac OS X v10.5 and later.
Declared in CMSDecoder.h
.
kCMSSignerNeedsDetachedContent
The message was signed but has detached content. You must call the CMSDecoderSetDetachedContent
function before ascertaining the signature status.
Available in Mac OS X v10.5 and later.
Declared in CMSDecoder.h
.
kCMSSignerInvalidSignature
The message was signed but the signature is invalid.
Available in Mac OS X v10.5 and later.
Declared in CMSDecoder.h
.
kCMSSignerInvalidCert
The message was signed but the signer's certificate could not be verified.
Available in Mac OS X v10.5 and later.
Declared in CMSDecoder.h
.
kCMSSignerInvalidIndex
The specified value for the signer index (signerIndex
parameter) is greater than the number of signers of the message minus one (signerIndex > (numSigners – 1)
).
Available in Mac OS X v10.5 and later.
Declared in CMSDecoder.h
.
CMSDecoder.h
Security API result codes are defined in Security/Secbase.h and listed in the table below. The assigned error space for security APIs is discontinuous: –25240 through –25279 and –25290 through –25329. Security APIs may also return noErr
(0) or paramErr
(–50), or CSSM result codes (see Common Security: CDSA and CSSM, version 2 (with corrigenda) from The Open Group (http://www.opengroup.org/security/cdsa.htm)).
© 2007 Apple Inc. All Rights Reserved. (Last updated: 2007-10-31)