TLSIdentity represents identity information, including an RSA key pair and certificates, used for server or client authentication as well as data encryption / decryption in TLS communication.
More...
|
| enum | CBLSignatureDigestAlgorithm : int {
kCBLSignatureDigestNone = 0
, kCBLSignatureDigestSHA1 = 4
, kCBLSignatureDigestSHA224
, kCBLSignatureDigestSHA256
,
kCBLSignatureDigestSHA384
, kCBLSignatureDigestSHA512
, kCBLSignatureDigestRIPEMD160
} |
| | Digest algorithms to be used when generating signatures with a private key. More...
|
| |
| _cbl_warn_unused CBLKeyPair *_cbl_nullable | CBLKeyPair_CreateWithExternalKey (size_t keySizeInBits, void *externalKey, CBLExternalKeyCallbacks callbacks, CBLError *_cbl_nullable outError) |
| | Returns an RSA key pair object that wraps an external key pair managed by application code. More...
|
| |
| _cbl_warn_unused CBLKeyPair *_cbl_nullable | CBLKeyPair_CreateWithPrivateKeyData (FLSlice privateKeyData, FLSlice passwordOrNull, CBLError *_cbl_nullable outError) |
| | Creates an RSA KeyPair from private key data in PEM or DER format. More...
|
| |
| _cbl_warn_unused FLSliceResult | CBLKeyPair_PublicKeyDigest (CBLKeyPair *keyPair) |
| | Returns a hex-encoded digest of the public key. More...
|
| |
| _cbl_warn_unused FLSliceResult | CBLKeyPair_PublicKeyData (CBLKeyPair *keyPair) |
| | Returns the public key data. More...
|
| |
| _cbl_warn_unused FLSliceResult | CBLKeyPair_PrivateKeyData (CBLKeyPair *keyPair) |
| | Returns the private key data, if the private key is known and its data is accessible. More...
|
| |
|
| enum | CBLKeyUsages : uint16_t { kCBLKeyUsagesClientAuth = 0x80
, kCBLKeyUsagesServerAuth = 0x40
} |
| | Defines key usage options for creating self-signed TLS identities. More...
|
| |
| typedef struct CBLTLSIdentity | CBLTLSIdentity |
| | An opaque object representing the TLSIdentity. More...
|
| |
| static const CBLTLSIdentity * | CBLTLSIdentity_Retain (const CBLTLSIdentity *t) |
| |
| static void | CBLTLSIdentity_Release (const CBLTLSIdentity *t) |
| |
| _cbl_warn_unused CBLCert * | CBLTLSIdentity_Certificates (CBLTLSIdentity *identity) |
| | Returns the certificate chain associated with the given TLS identity. More...
|
| |
| CBLTimestamp | CBLTLSIdentity_Expiration (CBLTLSIdentity *identity) |
| | Returns the date/time at which the first certificate in the chain expires. More...
|
| |
| _cbl_warn_unused CBLTLSIdentity *_cbl_nullable | CBLTLSIdentity_CreateIdentity (CBLKeyUsages keyUsages, FLDict attributes, CBLTimestamp expiration, FLString label, CBLError *_cbl_nullable outError) |
| | Creates a self-signed TLS identity using the specified certificate attributes. More...
|
| |
| _cbl_warn_unused CBLTLSIdentity *_cbl_nullable | CBLTLSIdentity_CreateIdentityWithKeyPair (CBLKeyUsages keyUsages, CBLKeyPair *keypair, FLDict attributes, CBLTimestamp expiration, CBLError *_cbl_nullable outError) |
| | Creates a self-signed TLS identity using the provided RSA key pair and certificate attributes. More...
|
| |
| bool | CBLTLSIdentity_DeleteIdentityWithLabel (FLString label, CBLError *_cbl_nullable outError) |
| | Deletes the TLS identity associated with the given persistent label from the platform's keystore (Keychain on Apple platforms or CNG Key Storage Provider on Windows). More...
|
| |
| _cbl_warn_unused CBLTLSIdentity *_cbl_nullable | CBLTLSIdentity_IdentityWithLabel (FLString label, CBLError *_cbl_nullable outError) |
| | Retrieves a TLS identity associated with the given persistent label from the platform's keystore (Keychain on Apple platforms or CNG Key Storage Provider on Windows). More...
|
| |
| _cbl_warn_unused CBLTLSIdentity *_cbl_nullable | CBLTLSIdentity_IdentityWithKeyPairAndCerts (CBLKeyPair *keypair, CBLCert *cert, CBLError *_cbl_nullable outError) |
| | Returns a TLS identity from an existing identity using the provided RSA keypair and certificate. More...
|
| |
| _cbl_warn_unused CBLTLSIdentity *_cbl_nullable | CBLTLSIdentity_IdentityWithCerts (CBLCert *cert, CBLError *_cbl_nullable outError) |
| | Returns an existing TLS identity associated with the provided certificate chain in the keystore (Keychain for Apple or CNG Key Storage Provider for Windows). More...
|
| |
TLSIdentity represents identity information, including an RSA key pair and certificates, used for server or client authentication as well as data encryption / decryption in TLS communication.
Couchbase Lite C provides functions for generating a new self-signed identity or using an existing identity. Similar to other Couchbase Lite platforms, when using Couchbase Lite C, a generated self-signed identity can be persisted using a specified label in the secure key storage, depending on the operating system as follows:
Apple (macOS and iOS) & Windows
The generated identity will be stored in the platform’s secure key storage as follows:
- Apple: The identity is stored in the Keychain.
- Windows: The identity is stored in CNG Key Storage Provider
Linux and Android
Due to the limitation that Linux-based operating systems do not have a standard or common secure key storage, and Android doesn’t support native C/C++ API access to the default keystore, Couchbase Lite C does not support persisting generated identities with the specified label on these platforms.
Alternatively, Couchbase Lite C allows developers to implement their own cryptographic operations through a set of callbacks, enabling certificate signing and data encryption / decryption using a private key stored in their preferred secure key storage. The key idea is that all cryptographic operations are performed within the secure key storage without exposing the private key.
◆ CBLCert
An opaque object representing the X.509 Certifcate.
◆ CBLKeyPair
An opaque object representing the key pair.
◆ CBLTLSIdentity
An opaque object representing the TLSIdentity.
◆ CBLKeyUsages
Defines key usage options for creating self-signed TLS identities.
This enumeration specifies whether a key can be used for client or server authentication. The values can be combined using bitwise OR (|) to allow multiple usages.
| Enumerator |
|---|
| kCBLKeyUsagesClientAuth | For client authentication.
|
| kCBLKeyUsagesServerAuth | For server authentication.
|
◆ CBLSignatureDigestAlgorithm
Digest algorithms to be used when generating signatures with a private key.
| Enumerator |
|---|
| kCBLSignatureDigestNone | No digest, just direct signature of input data.
|
| kCBLSignatureDigestSHA1 | SHA-1 message digest.
|
| kCBLSignatureDigestSHA224 | SHA-224 message digest.
|
| kCBLSignatureDigestSHA256 | SHA-256 message digest.
|
| kCBLSignatureDigestSHA384 | SHA-384 message digest.
|
| kCBLSignatureDigestSHA512 | SHA-512 message digest.
|
| kCBLSignatureDigestRIPEMD160 | RIPEMD-160 message digest.
|
◆ CBLCert_CertNextInChain()
Gets the next certificate in the chain if presents.
- Parameters
-
| cert | The current certificate. |
- Returns
- A CBLCert instance of the next certificte in the chain, or NULL if none is presents.
- Note
- You are responsible for releasing the returned reference.
◆ CBLCert_CreateWithData()
Creates a CBLCert from X.509 certificate data in DER or PEM format.
- Parameters
-
| certData | The certificate data in DER or PEM format. |
| outError | On failure, the error will be written here. |
- Returns
- A CBLCert instance on success, or NULL on failure.
- Note
- PEM data might consist of a series of certificates. If so, the returned CBLCert will represent only the first, and you can iterate over the next by calling CBLCert_NextInChain.
-
You are responsible for releasing the returned reference.
◆ CBLCert_Data()
Returns the X.509 certificate data in either DER or PEM format.
- Parameters
-
| cert | The certificate. |
| pemEncoded | If true, returns the data in PEM format; otherwise, returns DER format. |
- Returns
- Certificate data in either DER or PEM format.
- Note
- DER format can only encode a single certificate, so if this CBLCert includes multiple certificates, use PEM format to preserve them.
-
You are responsible for releasing the returned data.
◆ CBLCert_PublicKey()
Returns a certificate's public key.
- Note
- You are responsible for releasing the returned key reference.
◆ CBLCert_Release()
| static void CBLCert_Release |
( |
const CBLCert * |
t | ) |
|
|
inlinestatic |
◆ CBLCert_Retain()
◆ CBLCert_SubjectName()
Returns the certificate's Subject Name, which identifies the cert's owner.
This is an X.509 structured string consisting of "KEY=VALUE" pairs separated by commas, where the keys are attribute names. (Commas in values are backslash-escaped.)
- Parameters
-
- Returns
- The certificate's Subject Name.
- Note
- Rather than parsing this yourself, use CBLCert_SubjectNameComponent.
-
You are responsible for releasing the returned data.
◆ CBLCert_SubjectNameComponent()
Returns a component of the certificate's subject name that matches the specified attribute key.
- Parameters
-
| cert | The certificate. |
| attributeKey | The subject name attribute key to look for |
- Returns
- A string containing the first matching component of the subject name, or NULL if not found.
- Note
- You are responsible for releasing the returned string.
◆ CBLCert_ValidTimespan()
Returns the time range during which a certificate is valid.
- Parameters
-
| cert | The certificate. |
| outCreated | On return, the date/time the cert became valid (was signed). |
| outExpires | On return, the date/time at which the certificate expires. |
◆ CBLKeyPair_CreateWithExternalKey()
Returns an RSA key pair object that wraps an external key pair managed by application code.
All private key operations (signing and decryption) are delegated to the specified callbacks.
- Parameters
-
| keySizeInBits | The size of the RSA key in bits (e.g., 2048 or 4096). |
| externalKey | An opaque pointer that will be passed to the callbacks. Typically a pointer to your own external key object. |
| callbacks | A set of callback functions used to perform cryptographic operations using the external key. |
| outError | On failure, the error will be written here. |
- Returns
- A CBLKeyPair instance on success, or NULL on failure.
- Note
- You are responsible for releasing the returned KeyPair
◆ CBLKeyPair_CreateWithPrivateKeyData()
Creates an RSA KeyPair from private key data in PEM or DER format.
- Parameters
-
| privateKeyData | The private key data in either PEM or DER format. |
| passwordOrNull | The password used to decrypt the key, or NULL if the key is not encrypted. |
| outError | On failure, the error will be written here. |
- Returns
- A CBLKeyPair instance on success, or NULL on failure.
- Note
- Only PKCS#1 format for private keys is supported.
-
You are responsible for releasig the returned KeyPair.
◆ CBLKeyPair_PrivateKeyData()
Returns the private key data, if the private key is known and its data is accessible.
- Parameters
-
| keyPair | The key pair containing the private key. |
- Returns
- The private key data, or an empty slice if the key is not accessible.
- Note
- Persistent private keys in the secure key store generally don't have accessible data.
-
You are responsible for releasing the returned data.
◆ CBLKeyPair_PublicKeyData()
Returns the public key data.
- Parameters
-
| keyPair | The key pair from which to retrieve the public key. |
- Returns
- The public key data.
- Note
- You are responsible for releasing the returned data.
◆ CBLKeyPair_PublicKeyDigest()
Returns a hex-encoded digest of the public key.
- Parameters
-
| keyPair | The key pair from which to extract the public key digest. |
- Returns
- A hex-encoded digest of the public key.
- Note
- You are responsible for releasing the returned data.
◆ CBLKeyPair_Release()
| static void CBLKeyPair_Release |
( |
const CBLKeyPair * |
t | ) |
|
|
inlinestatic |
◆ CBLKeyPair_Retain()
◆ CBLTLSIdentity_Certificates()
Returns the certificate chain associated with the given TLS identity.
- Parameters
-
| identity | The TLS identity. |
- Returns
- The first certificate in the chain. Use CBLCert_CertNextInChain to access additional certificates.
◆ CBLTLSIdentity_CreateIdentity()
Creates a self-signed TLS identity using the specified certificate attributes.
If a non-NULL label (kFLSliceNull indicates NULL) is provided, the identity will be persisted in the platform's secure key store (Keychain on Apple platforms or CNG Key Storage Provider on Windows).
- Parameters
-
| keyUsages | The key usages for the generated identity. |
| attributes | A dictionary containing the certificate attributes. |
| expiration | The expiration date/time of the certificate in the identity. |
| label | The label used for persisting the identity in the platform's secure storage. If kFLSliceNull is passed, the identity will not be persisted. |
| outError | On failure, the error will be written here. |
- Returns
- A CBLTLSIdentity instance on success, or NULL on failure.
- Note
- A non-NULL label is not supported on Linux or Android platforms. On these platforms, passing
kFLSliceNull for the label is required. @Note The Common Name (kCBLCertAttrKeyCommonName) attribute is required. @Note You are responsible for releasing the returned reference.
◆ CBLTLSIdentity_CreateIdentityWithKeyPair()
Creates a self-signed TLS identity using the provided RSA key pair and certificate attributes.
- Parameters
-
| keyUsages | The key usages for the generated identity. |
| keypair | The RSA key pair to be used for generating the TLS identity. |
| attributes | A dictionary containing the certificate attributes. |
| expiration | The expiration date/time of the certificate in the identity. |
| outError | On failure, the error will be written here. |
- Returns
- A CBLTLSIdentity instance on success, or NULL on failure. @Note The Common Name (kCBLCertAttrKeyCommonName) attribute is required. @Note You are responsible for releasig the returned reference.
◆ CBLTLSIdentity_DeleteIdentityWithLabel()
Deletes the TLS identity associated with the given persistent label from the platform's keystore (Keychain on Apple platforms or CNG Key Storage Provider on Windows).
- Parameters
-
| label | The persistent label associated with the identity to be deleted. |
| outError | On failure, the error will be written here. |
- Returns
true if the identity was successfully deleted, or false on failure.
- Note
- This function is not supported on Linux or Android platforms.
◆ CBLTLSIdentity_Expiration()
Returns the date/time at which the first certificate in the chain expires.
Returns the expiration date/time of the first certificate in the chain.
- Parameters
-
- Returns
- The expiration timestamp of the first certificate.
◆ CBLTLSIdentity_IdentityWithCerts()
Returns an existing TLS identity associated with the provided certificate chain in the keystore (Keychain for Apple or CNG Key Storage Provider for Windows).
The keypair will be looked up by the first certificate in the chain.
- Parameters
-
| cert | A CBLCert instance representing the certificate chain. |
| outError | On failure, the error will be written here. |
- Returns
- A CBLTLSIdentity instance on success, or
NULL if an error occurs. @Note The Linux and Android platforms do not support this function.
- Note
- You are responsible for releasing the returned reference.
◆ CBLTLSIdentity_IdentityWithKeyPairAndCerts()
Returns a TLS identity from an existing identity using the provided RSA keypair and certificate.
The certificate will not be resigned with the new keypair; it will be used as is.
- Parameters
-
| keypair | A CBLKeyPair instance representing the RSA keypair to be associated with the identity. |
| cert | A CBLCert instance representing the certificate associated with the identity. |
| outError | On failure, the error will be written here. |
- Returns
- A CBLTLSIdentity instance on success, or
NULL if an error occurs.
- Note
- You are responsible for releasing the returned reference.
◆ CBLTLSIdentity_IdentityWithLabel()
Retrieves a TLS identity associated with the given persistent label from the platform's keystore (Keychain on Apple platforms or CNG Key Storage Provider on Windows).
- Parameters
-
| label | The persistent label associated with the identity to be deleted. |
| outError | On failure, the error will be written here. |
- Returns
- A CBLTLSIdentity instance if the identity is found and successfully retrieved, or
NULL if the identity does not exist or an error occurs. @Note The Linux and Android platforms do not support this function.
- Note
- You are responsible for releasing the returned reference.
◆ CBLTLSIdentity_Release()
◆ CBLTLSIdentity_Retain()
◆ kCBLCertAttrKeyCommonName
◆ kCBLCertAttrKeyCountry
◆ kCBLCertAttrKeyEmailAddress
◆ kCBLCertAttrKeyGivenName
◆ kCBLCertAttrKeyHostname
◆ kCBLCertAttrKeyIPAddress
◆ kCBLCertAttrKeyLocality
◆ kCBLCertAttrKeyOrganization
◆ kCBLCertAttrKeyOrganizationUnit
◆ kCBLCertAttrKeyPostalAddress
◆ kCBLCertAttrKeyPostalCode
◆ kCBLCertAttrKeyPseudonym
◆ kCBLCertAttrKeyRegisteredID
◆ kCBLCertAttrKeyStateOrProvince
◆ kCBLCertAttrKeySurname
◆ kCBLCertAttrKeyURL
