Certificates

Manage digital certificates.

Overview

A digital certificate is a collection of data used to securely distribute the public half of a public/private key pair. Figure 1 shows the parts of a typical X.509 certificate that make this possible. Along with structural information, the certificate contains name and contact information for both its issuer and its owner (or subject), plus the owner's public key. A date range indicates when the certificate is valid. Certificate extensions provide additional information and conditions, like acceptable uses for the public key. When assembling the certificate, to vouch for its integrity, the issuer digitally signs it using the issuer's own identity (private key and certificate).

Figure 1

Contents of an X.509 certificate

Diagram showing the components of an X.509 certificate, including the version and serial number, the subject and issuer, the validity dates, the public key, the signature, and the extensions.

To evaluate a certificate, you first verify its signature using the specified algorithm and the issuer's public key, which you obtain from the issuer's publicly available certificate. A valid signature confirms that the certificate under evaluation, known as the leaf certificate, is unaltered. But in order to trust this result, you must also trust the issuer's certificate. You use a similar procedure to test this certificate, and the one that guarantees that certificate, and the next, and so on in a chain back to a trusted root authority whose certificate, known as the anchor, which you trust implicitly. The public key included in the leaf certificate is then considered trustworthy. You can be assured that it has come unaltered from the certificate's owner who controls the corresponding private key. This allows you to securely use the public key to engage in asymmetric cryptography with the certificate's owner.

For more details about how certificates work, read Digital Certificates in Cryptographic Services Guide.

Topics

Essentials

Getting a Certificate

Obtain a certificate from an identity, from DER-encoded data, or from the keychain.

Storing a Certificate in the Keychain

Store a certificate in the keychain for safekeeping.

SecCertificateRef

An abstract Core Foundation-type object representing an X.509 certificate.

SecCertificateGetTypeID

Returns the unique identifier of the opaque type to which a certificate object belongs.

Import and Export

Storing a DER-Encoded X.509 Certificate

Import and export a certificate from a file.

SecCertificateCreateWithData

Creates a certificate object from a DER representation of a certificate.

SecCertificateCopyData

Returns a DER representation of a certificate given a certificate object.

Certificate Components

Examining a Certificate

Learn how to retrieve properties from a certificate.

SecCertificateCopySubjectSummary

Returns a human-readable summary of a certificate.

SecCertificateCopyCommonName

Retrieves the common name of the subject of a certificate.

SecCertificateCopyEmailAddresses

Retrieves the email addresses for the subject of a certificate.

SecCertificateCopyNormalizedIssuerSequence

Retrieves the normalized issuer sequence from a certificate.

SecCertificateCopyNormalizedSubjectSequence

Retrieves the normalized subject sequence from a certificate.

SecCertificateCopySerialNumberData

Returns the certificate’s serial number.

SecCertificateCopyKey

Retrieves the public key for a given certificate.

SecCertificateCopyShortDescription

Returns a copy of the short description of a certificate.

SecCertificateCopyLongDescription

Returns a copy of the long description of a certificate.

Detailed Certificate Information

Getting Certificate Values

Obtain all the values associated with a certificate.

SecCertificateCopyValues

Creates a dictionary that represents a certificate's contents.

Certificate OIDs

Use OIDs as keys in the dictionary representing certificate values.

Certificate Property Keys

Recognize the dictionary keys that taken together define a certificate property.

Certificate Property Type Values

Recognize the possible certificate property types.

Certificate Item Attribute Constants

Use these four character values to indicate certificate item attributes.

Certificate Names

SecCertificateSetPreferred

Sets the certificate that should be preferred for the specified name and key use.

SecCertificateCopyPreferred

Returns the preferred certificate for the specified name and key usage.

Legacy Symbols

SecCertificateAddToKeychain

Adds a certificate to a keychain.

SecCertificateCopyNormalizedIssuerContent

Returns a normalized copy of the distinguished name (DN) of the issuer of a certificate.

Deprecated
SecCertificateCopyNormalizedSubjectContent

Returns a normalized copy of the distinguished name (DN) of the subject of a certificate.

Deprecated
SecCertificateCreateFromData

Creates a certificate object based on the specified data, type, and encoding.

Deprecated
SecCertificateCopyPreference

Retrieves the preferred certificate for the specified name and key use.

Deprecated
SecCertificateGetAlgorithmID

Retrieves the algorithm identifier for a certificate.

Deprecated
SecCertificateGetCLHandle

Retrieves the certificate library handle from a certificate object.

Deprecated
SecCertificateGetData

Retrieves the data for a certificate.

Deprecated
SecCertificateGetIssuer

Unsupported.

Deprecated
SecCertificateGetSubject

Unsupported.

Deprecated
SecCertificateGetType

Retrieves the type of a specified certificate.

Deprecated
SecCertificateSetPreference

Sets the preferred certificate for a specified name, key use, and date.

Deprecated
SecCertificateCopySerialNumber

Returns a copy of a certificate’s serial number.

Deprecated
SecCertificateCopyPublicKey

Retrieves the public key from a certificate.

Deprecated

See Also

API Components

Keys

Generate, store, and use cryptographic keys.

Identities

Combine certificates and cryptographic keys into identities.

Policies

Obtain policies for establishing trust.

Trust

Evaluate trust based on a given policy.