Cryptographic Message Syntax Services

Cryptographic Message Syntax Services is an API that implements Cryptographic Message Syntax (CMS) digital signatures and encryption for S/MIME messages.

Overview

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)

Symbols

Initializing The Encoder

func CMSEncoderGetTypeID()

Returns the type identifier for the CMSEncoder opaque type.

Specifying Message Characteristics

func CMSEncoderAddSigners(CMSEncoder, CFTypeRef)

Specifies signers of the message.

func CMSEncoderCopySigners(CMSEncoder, UnsafeMutablePointer<CFArray?>)

Obtains the array of signers specified with the CMSEncoderAddSigners function.

func CMSEncoderAddRecipients(CMSEncoder, CFTypeRef)

Specifies a message is to be encrypted and specifies the recipients of the message.

func CMSEncoderCopyRecipients(CMSEncoder, UnsafeMutablePointer<CFArray?>)

Obtains the array of recipients specified with the CMSEncoderAddRecipients function.

func CMSEncoderSetHasDetachedContent(CMSEncoder, Bool)

Specifies whether the signed data is to be separate from the message.

func CMSEncoderGetHasDetachedContent(CMSEncoder, UnsafeMutablePointer<DarwinBoolean>)

Indicates whether the message is to have detached content.

func CMSEncoderSetEncapsulatedContentTypeOID(CMSEncoder, CFTypeRef)

Specifies an object identifier for the encapsulated data of a signed message.

func CMSEncoderSetEncapsulatedContentType(CMSEncoder, UnsafePointer<CSSM_OID>)

Specifies an object identifier for the encapsulated data of a signed message.

func CMSEncoderCopyEncapsulatedContentType(CMSEncoder, UnsafeMutablePointer<CFData?>)

Obtains the object identifier for the encapsulated data of a signed message.

func CMSEncoderCopySupportingCerts(CMSEncoder, UnsafeMutablePointer<CFArray?>)

Obtains the certificates added to a message with CMSEncoderAddSupportingCerts.

func CMSEncoderSetCertificateChainMode(CMSEncoder, CMSCertificateChainMode)

Specifies which certificates to include in a signed CMS message.

func CMSEncoderGetCertificateChainMode(CMSEncoder, UnsafeMutablePointer<CMSCertificateChainMode>)

Obtains a constant that indicates which certificates are to be included in a signed CMS message.

Initializing The Decoder

func CMSDecoderGetTypeID()

Returns the type identifier for the CMSDecoder opaque type.

Decoding The Message

func CMSDecoderUpdateMessage(CMSDecoder, UnsafeRawPointer, Int)

Feeds raw bytes of the message to be decoded into the decoder.

func CMSDecoderFinalizeMessage(CMSDecoder)

Indicates that there is no more data to decode.

func CMSDecoderSetDetachedContent(CMSDecoder, CFData)

Specifies the message’s detached content, if any.

func CMSDecoderCopyDetachedContent(CMSDecoder, UnsafeMutablePointer<CFData?>)

Obtains the detached content specified with the CMSDecoderSetDetachedContent function.

Verifying The Signature

func CMSDecoderSetSearchKeychain(CMSDecoder, CFTypeRef)

Specifies the keychains to search for intermediate certificates to be used in verifying a signed message's signer certificates.

func CMSDecoderCopySignerEmailAddress(CMSDecoder, Int, UnsafeMutablePointer<CFString?>)

Obtains the email address of the specified signer of a CMS message.

func CMSDecoderCopySignerCert(CMSDecoder, Int, UnsafeMutablePointer<SecCertificate?>)

Obtains the certificate of the specified signer of a CMS message.

Obtaining Message Content

func CMSDecoderCopyEncapsulatedContentType(CMSDecoder, UnsafeMutablePointer<CFData?>)

Obtains the object identifier for the encapsulated data of a signed message.

func CMSDecoderCopyAllCerts(CMSDecoder, UnsafeMutablePointer<CFArray?>)

Obtain an array of all of the certificates in a message.

Working with Time Stamps

func CMSDecoderCopySignerTimestamp(CMSDecoder, Int, UnsafeMutablePointer<CFAbsoluteTime>)

Returns the time stamp of a signer of a CMS message, if present.

func CMSDecoderCopySignerTimestampCertificates(CMSDecoder, Int, UnsafeMutablePointer<CFArray?>)

Returns an array containing the certificates from a timestamp response.

func CMSEncoderCopySignerTimestamp(CMSEncoder, Int, UnsafeMutablePointer<CFAbsoluteTime>)

Returns the time stamp of a signer of a CMS message, if present.

Data Types

CMSEncoder

Opaque reference to a CMS encoder object.

CMSDecoder

Opaque reference to a CMS decoder object.

Constants

CMSSignedAttributes

Optional attributes that can be specified with the CMSEncoderAddSignedAttributes(_:_:) function.

CMSCertificateChainMode

Constants that can be set by the CMSEncoderSetCertificateChainMode(_:_:) function to specify what certificates to include in a signed message.

CMSSignerStatus

Constants that indicate the status of the signature and signer information in a signed message, as obtained by the CMSDecoderCopySignerStatus(_:_:_:_:_:_:_:) function.

Result Codes

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)).

var errSecNotAvailable: OSStatus

No trust results are available.

var errSecAuthFailed: OSStatus

Authorization/Authentication failed.

var errSecNoSuchKeychain: OSStatus

The keychain does not exist.

var errSecInvalidKeychain: OSStatus

The keychain is not valid.

var errSecDuplicateKeychain: OSStatus

A keychain with the same name already exists.

var errSecDuplicateCallback: OSStatus

More than one callback of the same name exists.

var errSecInvalidCallback: OSStatus

The callback is not valid.

var errSecDuplicateItem: OSStatus

The item already exists.

var errSecItemNotFound: OSStatus

The item cannot be found.

var errSecBufferTooSmall: OSStatus

The buffer is too small.

var errSecDataTooLarge: OSStatus

The data is too large for the particular data type.

var errSecNoSuchAttr: OSStatus

The attribute does not exist.

var errSecInvalidItemRef: OSStatus

The item reference is invalid.

var errSecInvalidSearchRef: OSStatus

The search reference is invalid.

var errSecNoSuchClass: OSStatus

The keychain item class does not exist.

var errSecNoDefaultKeychain: OSStatus

A default keychain does not exist.

var errSecInteractionNotAllowed: OSStatus

Interaction with the Security Server is not allowed.

var errSecReadOnlyAttr: OSStatus

The attribute is read only.

var errSecWrongSecVersion: OSStatus

The version is incorrect.

var errSecKeySizeNotAllowed: OSStatus

The key size is not allowed.

var errSecNoStorageModule: OSStatus

There is no storage module available.

var errSecNoCertificateModule: OSStatus

There is no certificate module available.

var errSecNoPolicyModule: OSStatus

There is no policy module available.

var errSecInteractionRequired: OSStatus

User interaction is required.

var errSecDataNotAvailable: OSStatus

The data is not available.

var errSecDataNotModifiable: OSStatus

The data is not modifiable.

var errSecCreateChainFailed: OSStatus

The attempt to create a certificate chain failed.

var errSecInvalidPrefsDomain: OSStatus

The preference domain specified is invalid. This error is available in macOS 10.3 and later.

var errSecACLNotSimple: OSStatus

The access control list is not in standard simple form.

var errSecPolicyNotFound: OSStatus

The policy specified cannot be found.

var errSecInvalidTrustSetting: OSStatus

The trust setting is invalid.

var errSecNoAccessForItem: OSStatus

The specified item has no access control.

var errSecInvalidOwnerEdit: OSStatus

An invalid attempt to change the owner of an item.

var errSecTrustNotAvailable: OSStatus

No trust results are available.

var errSecUnsupportedFormat: OSStatus

The specified import or export format is not supported.

var errSecUnknownFormat: OSStatus

The item you are trying to import has an unknown format.

var errSecKeyIsSensitive: OSStatus

The key must be wrapped to be exported.

var errSecMultiplePrivKeys: OSStatus

An attempt was made to import multiple private keys.

var errSecPassphraseRequired: OSStatus

A password is required for import or export.