/** * @file * This file defines the alljoyn_permissionconfigurator and related functions. */ /****************************************************************************** * Copyright AllSeen Alliance. All rights reserved. * * Permission to use, copy, modify, and/or distribute this software for any * purpose with or without fee is hereby granted, provided that the above * copyright notice and this permission notice appear in all copies. * * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. ******************************************************************************/ #ifndef _ALLJOYN_C_PERMISSIONCONFIGURATOR_H #define _ALLJOYN_C_PERMISSIONCONFIGURATOR_H #include #ifdef __cplusplus extern "C" { #endif /** * alljoyn_permissionconfigurator is a handle which exposes Security 2.0 permission * management capabilities to the application. */ typedef struct _alljoyn_permissionconfigurator_handle* alljoyn_permissionconfigurator; /** * Enum defining the application's current state. */ typedef enum { NOT_CLAIMABLE, /**< The application is not claimed and not accepting claim requests. */ CLAIMABLE, /**< The application is not claimed and is accepting claim requests. */ CLAIMED, /**< The application is claimed and can be configured. */ NEED_UPDATE /**< The application is claimed, but requires a configuration update (after a software upgrade). */ } alljoyn_applicationstate; /** * Bitmasks used to indicate possible ways to claim the app. */ typedef uint16_t alljoyn_claimcapabilities; typedef enum { CAPABLE_ECDHE_NULL = 0x0001, CAPABLE_ECDHE_ECDSA = 0x0004, CAPABLE_ECDHE_SPEKE = 0x0008 } alljoyn_claimcapability_masks; /** * Bitmasks used to indicate password source. */ typedef uint16_t alljoyn_claimcapabilitiesadditionalinfo; typedef enum { PASSWORD_GENERATED_BY_SECURITY_MANAGER = 0x0001, PASSWORD_GENERATED_BY_APPLICATION = 0x0002 } alljoyn_claimcapabilityadditionalinfo_masks; /** * Get the default claim capabilities bitmask. * * @return alljoyn_claimcapabilities containing the default capability set. */ AJ_API alljoyn_claimcapabilities AJ_CALL alljoyn_permissionconfigurator_getdefaultclaimcapabilities(); /** * Struct used to return identifying information about a certificate. */ typedef struct { uint8_t* serial; /**< The certificate's serial number. */ size_t serialLen; /**< The certificate's serial number length. */ AJ_PSTR issuerPublicKey; /**< The certificate issuer's public key in PEM format. */ uint8_t* issuerAki; /**< The certificate issuer's AKI. */ size_t issuerAkiLen; /**< The certificate issuer's AKI length. */ } alljoyn_certificateid; /** * Struct used to return an array of alljoyn_certificateid. */ typedef struct { size_t count; /**< The number of elements in the certficateIds array. */ alljoyn_certificateid* ids; /**< An array of alljoyn_certificateid. */ } alljoyn_certificateidarray; /** * Struct used to return an array of manifest XMLs. */ typedef struct { size_t count; /**< The number of elements in the xmls array. */ AJ_PSTR* xmls; /**< An array of strings, each containing a signed manifest XML. */ } alljoyn_manifestarray; /** * Retrieves the current application state. * * @param[in] configurator The queried alljoyn_permissionconfigurator. * @param[out] state Returned state. * * @return * #ER_OK if successful. * Other error status codes indicating a failure. */ AJ_API QStatus AJ_CALL alljoyn_permissionconfigurator_getapplicationstate(const alljoyn_permissionconfigurator configurator, alljoyn_applicationstate* state); /** * Set the application state. The state cannot be changed from CLAIMED to CLAIMABLE. * * @param[in] configurator The queried alljoyn_permissionconfigurator. * @param[in] state New state. * * @return * #ER_OK if action is allowed. * #ER_INVALID_APPLICATION_STATE if the state can't be changed. * Other error status codes indicating a failure. */ AJ_API QStatus AJ_CALL alljoyn_permissionconfigurator_setapplicationstate(alljoyn_permissionconfigurator configurator, alljoyn_applicationstate state); /** * Get the application's public key. * * @param[in] configurator The queried alljoyn_permissionconfigurator. * @param[out] publicKey Pointer to receive the null-terminated C string with the PEM-encoded representation * of the application's public key. On success, this string must be freed with a call * to alljoyn_permissionconfigurator_publickey_destroy. * * @return * #ER_OK if successful. * Other error status codes indicating a failure. */ AJ_API QStatus AJ_CALL alljoyn_permissionconfigurator_getpublickey(alljoyn_permissionconfigurator configurator, AJ_PSTR* publicKey); /** * Destroy a string returned by a call to alljoyn_permissionconfigurator_getpublickey. * * @param[in] publicKey String received from the call to alljoyn_permissionconfigurator_getpublickey. */ AJ_API void AJ_CALL alljoyn_permissionconfigurator_publickey_destroy(AJ_PSTR publicKey); /** * Get the application's manifest template as XML. * * @param[in] configurator The queried alljoyn_permissionconfigurator. * @param[out] manifestTemplateXml Pointer to receive null-terminated C string containing manifest template * as XML. On success, this string must be freed using * alljoyn_permissionconfigurator_manifesttemplate_destroy. * * @return * #ER_OK if successful. * Other error status codes indicating a failure. */ AJ_API QStatus AJ_CALL alljoyn_permissionconfigurator_getmanifesttemplate(alljoyn_permissionconfigurator configurator, AJ_PSTR* manifestTemplateXml); /** * Destroy a string received from a call to alljoyn_permissionconfigurator_getmanifesttemplate. * * @param[in] manifestTemplateXml String received from the call. * */ AJ_API void AJ_CALL alljoyn_permissionconfigurator_manifesttemplate_destroy(AJ_PSTR manifestTemplateXml); /** * Set the application's manifest template from an XML. * * @param[in] configurator The queried alljoyn_permissionconfigurator. * @param[in] manifestTemplateXml String containing the XML version of the manifest template. * * @return * #ER_OK if successful. * #ER_XML_MALFORMED if the XML is not in a valid manifest template format. * Other error status codes indicating a failure. */ AJ_API QStatus AJ_CALL alljoyn_permissionconfigurator_setmanifesttemplatefromxml(alljoyn_permissionconfigurator configurator, AJ_PCSTR manifestTemplateXml); /** * Get the authentication mechanisms the application supports for the * claim process. * * @param[in] configurator The queried alljoyn_permissionconfigurator. * @param[out] claimCapabilities The authentication mechanisms the application supports. * * @return * #ER_OK if successful. * An error status indicating failure. */ AJ_API QStatus AJ_CALL alljoyn_permissionconfigurator_getclaimcapabilities(const alljoyn_permissionconfigurator configurator, alljoyn_claimcapabilities* claimCapabilities); /** * Set the authentication mechanisms the application supports for the * claim process. It is a bit mask created by the bitwise OR of the * alljoyn_claimcapability_masks constants. * * @param[in] configurator The queried alljoyn_permissionconfigurator. * @param[in] claimCapabilities The authentication mechanisms the application supports. * * @return * #ER_OK if successful. * An error status indicating failure. */ AJ_API QStatus AJ_CALL alljoyn_permissionconfigurator_setclaimcapabilities(alljoyn_permissionconfigurator configurator, alljoyn_claimcapabilities claimCapabilities); /** * Get the additional information on the claim capabilities. * * @param[in] configurator The queried alljoyn_permissionconfigurator. * @param[out] additionalInfo The additional claim info. * * @return * #ER_OK if successful. * An error status indicating failure. */ AJ_API QStatus AJ_CALL alljoyn_permissionconfigurator_getclaimcapabilitiesadditionalinfo(const alljoyn_permissionconfigurator configurator, alljoyn_claimcapabilitiesadditionalinfo* additionalInfo); /** * Set the additional information on the claim capabilities. * It is a bit mask, created by the bitwise OR of the * alljoyn_claimcapabilityadditionalinfo_masks constants. * * @param[in] configurator The queried alljoyn_permissionconfigurator. * @param[in] additionalInfo The additional info. * * @return * #ER_OK if successful. * An error status indicating failure. */ AJ_API QStatus AJ_CALL alljoyn_permissionconfigurator_setclaimcapabilitiesadditionalinfo(alljoyn_permissionconfigurator configurator, alljoyn_claimcapabilitiesadditionalinfo additionalInfo); /** * Reset the permission settings by removing the manifest all the * trust anchors, installed policy and certificates. * * @param[in] configurator The alljoyn_permissionconfigurator performing the reset. * * @return * #ER_OK if successful. * An error code otherwise. */ AJ_API QStatus AJ_CALL alljoyn_permissionconfigurator_reset(alljoyn_permissionconfigurator configurator); /** * Claims the application. The application is provided an identity certificate chain with * its own cert as the leaf. The application automatically installs the policy to * allow all communication from the provided admin group. * The application's manifests are installed as well. Peer security must first be enabled on the bus attachment. * * To prevent a potential security-critical race condition, before claiming a bus attachment with this method, * it is recommended to call alljoyn_busattachment_enablepersecurity on an unclaimed bus attachment with * "ALLJOYN_ECDHE_ECDSA" only in the authMechanisms parameter. The default claim capabilities do not allow * ALLJOYN_ECDHE_ECDSA for claiming, and this will guarantee a rogue security manager on the same bus can't * claim this bus attachment before this function is called. Do not set claim capabilities on a bus attachment * that will be claimed with this function. * * After the bus attachment is claimed, alljoyn_busattachment_enablepeersecurity can be called again if any of * ALLJOYN_ECDHE_NULL, ALLJOYN_ECDHE_PSK, or ALLJOYN_ECDHE_SPEKE are required; this will usually only be required * if the bus attachment will be used by a security manager to claim other apps over the bus. See the documentation * for alljoyn_busattachment_enablepeersecurity for details on changing authentication mechanisms. * * @param[in] configurator The alljoyn_permissionconfigurator for the application's bus attachment. * @param[in] caKey Null-terminated C string representing the CA's PEM-encoded public key. * @param[in] identityCertificateChain Null-terminated C string representing PEM-encoded identity certificates * with the app's certificate being the leaf. The leaf is listed first * followed by each intermediate Certificate Authority's certificate, ending * in the trusted root's certificate. * @param[in] groupId Byte array representing the admin group GUID. * @param[in] groupSize Size of "groupId" array. It must be equal to 16. * @param[in] groupAuthority Null-terminated C string containing the PEM-encoded public key of the * security group authority. * @param[in] manifestsXmls An array of null-terminated C strings containing the application's * signed manifests in XML format. The signed manifest's XSD is located under * alljoyn_core/docs/manifest.xsd. * @param[in] manifestsCount Count of "manifestsXmls" array elements. * * @return * - #ER_OK If successful. * - Other error status codes indicating a failure. */ AJ_API QStatus AJ_CALL alljoyn_permissionconfigurator_claim(alljoyn_permissionconfigurator configurator, AJ_PCSTR caKey, AJ_PCSTR identityCertificateChain, const uint8_t* groupId, size_t groupSize, AJ_PCSTR groupAuthority, AJ_PCSTR* manifestsXmls, size_t manifestsCount); /** * This method allows the application to update its identity certificate and manifests. * All old manifests will be overwritten by the new set. * * After having a new identity certificate installed, the target bus clears * out all of its peer's secret and session keys, so the next call will get * security violation. After calling alljoyn_permissionconfigurator_updateidentity, * alljoyn_busattachment_secureconnectionasync(true) should be called to force * the peers to create a new set of secret and session keys. * * @param[in] configurator The alljoyn_permissionconfigurator for the application's bus attachment. * @param[in] identityCertificateChain Null-terminated C string representing PEM-encoded identity certificate chain * with the application's certificate being the leaf. The leaf is listed first * followed by each intermediate Certificate Authority's certificate, ending * in the trusted root's certificate. * @param[in] manifestsXmls An array of null-terminated C strings containing the application's * signed manifests in XML format. * @param[in] manifestsCount Count of "manifestsXmls" array elements. * * @return * - #ER_OK If successful. * - #ER_INVALID_CERTIFICATE Error raised when the identity certificate chain is not valid. * - #ER_INVALID_CERTIFICATE_USAGE Error raised when the Extended Key Usage is not AllJoyn specific. * - #ER_DIGEST_MISMATCH Error raised when none of the provided signed manifests are * valid for the given identity certificate. * - #ER_XML_MALFORMED Error raised the manifest is not compliant with the required format. * - An error status indicating failure. */ AJ_API QStatus AJ_CALL alljoyn_permissionconfigurator_updateidentity(alljoyn_permissionconfigurator configurator, AJ_PCSTR identityCertificateChain, AJ_PCSTR* manifestsXmls, size_t manifestsCount); /** * This method allows the application to retrieve its identity certificate chain. * * @param[in] configurator The alljoyn_permissionconfigurator for the application's bus attachment. * @param[out] identityCertificateChain Null-terminated C string representing PEM-encoded identity certificate chain * with the application's certificate being the leaf. The leaf is listed first * followed by each intermediate Certificate Authority's certificate, ending in * the trusted root's certificate. This string must be freed with * alljoyn_permissionconfigurator_certificatechain_destroy. * * @return * - #ER_OK If successful. * - #ER_CERTIFICATE_NOT_FOUND Error raised when no identity certificate chain is installed. * - An error status indicating failure. */ AJ_API QStatus AJ_CALL alljoyn_permissionconfigurator_getidentity(alljoyn_permissionconfigurator configurator, AJ_PSTR* identityCertificateChain); /** * This method deallocates a string of PEM-encoded certificates returned by alljoyn_permissionconfigurator_getidentity. * * @param[in] certificateChain String returned by a call to alljoyn_permissionconfigurator_getidentity. */ AJ_API void AJ_CALL alljoyn_permissionconfigurator_certificatechain_destroy(AJ_PSTR certificateChain); /** * This method allows the application to retrieve its signed manifests. * * @param[in] configurator The alljoyn_permissionconfigurator for the application's bus attachment. * @param[out] manifestArray Pointer to an alljoyn_manifestarray to receive manifests in * XML format. This array must be freed with * alljoyn_permissionconfigurator_manifestarray_cleanup. * * @return * - #ER_OK If successful. * - #ER_MANIFEST_NOT_FOUND Error raised when no manifests are installed. * - An error status indicating failure. */ AJ_API QStatus AJ_CALL alljoyn_permissionconfigurator_getmanifests(alljoyn_permissionconfigurator configurator, alljoyn_manifestarray* manifestArray); /** * This method deallocates an array of strings containing manifests returned by alljoyn_permissionconfigurator_getmanifests. * * @param[in] manifestArray Pointer to alljoyn_manifestarray populated by a call to * alljoyn_permissionconfigurator_getmanifests. */ AJ_API void AJ_CALL alljoyn_permissionconfigurator_manifestarray_cleanup(alljoyn_manifestarray* manifestArray); /** * This method allows the application to install signed manifests to itself. This method only verifies that manifests * have a signature; it does not verify that the signature is valid. * * @param[in] configurator The alljoyn_permissionconfigurator for the application's bus attachment. * @param[in] manifestsXmls Array of null-terminated C strings, each of which is a signed manifest in * XML format. * @param[in] manifestsCount The number of elements in the manifests array. * @param[in] append QCC_TRUE to append to the currently installed manifests; QCC_FALSE to clear * currently installed manifests first * * @return * - #ER_OK If successful. * - #ER_DIGEST_MISMATCH Error raised if no manifests can be installed because none are signed. * - An error status indicating failure. */ AJ_API QStatus AJ_CALL alljoyn_permissionconfigurator_installmanifests(alljoyn_permissionconfigurator configurator, AJ_PCSTR* manifestsXmls, size_t manifestsCount, QCC_BOOL append); /** * This method retrieves the application's identity certificate information. * * @param[in] configurator The alljoyn_permissionconfigurator for the application's bus attachment. * @param[out] certificateId Pointer to receive the alljoyn_certificateid structure containing the * serial number and issuer public key of the identity certificate. The * issuerAki field is not returned by this function and will be NULL. * This must be freed by the caller using alljoyn_permissionconfigurator_certificateid_cleanup. * * @return * - #ER_OK If successful. * - #ER_CERTIFICATE_NOT_FOUND Error raised when no identity certificate chain is installed. * - An error status indicating failure. */ AJ_API QStatus AJ_CALL alljoyn_permissionconfigurator_getidentitycertificateid(alljoyn_permissionconfigurator configurator, alljoyn_certificateid* certificateId); /** * This method deallocates strings returned by a call to alljoyn_permissionconfigurator_getidentitycertificateid. * * @param[in] certificateIdString Pointer to alljoyn_certificateid struct returned by a call to * alljoyn_permissionconfigurator_getidentitycertificateid. */ AJ_API void AJ_CALL alljoyn_permissionconfigurator_certificateid_cleanup(alljoyn_certificateid* certificateId); /** * This method allows the app to install the permission policy to itself. * Any existing policy will be replaced; the caller is responsible for first getting * the policy and checking the version number if the caller only wishes to replace * the policy with a newer version. * * Until ASACORE-2755 is fixed the caller must include all default policies * (containing information about the trust anchors) with each call, so they * would not be removed. * * After having a new policy installed, the target bus clears out all of * its peer's secret and session keys, so so any existing secure session will * need to be re-established: alljoyn_busattachment_secureconnectionasync(true) * should be called to force the peers to create a new set of secret and session keys. * * @param[in] configurator The alljoyn_permissionconfigurator for the application's bus attachment. * @param[in] policyXml The new policy in XML format. For the policy XSD refer to * alljoyn_core/docs/policy.xsd. * * @return * - #ER_OK If successful. * - #ER_XML_MALFORMED Error raised when the provided XML is not in supported policy format. * - An error status indicating failure. */ AJ_API QStatus AJ_CALL alljoyn_permissionconfigurator_updatepolicy(alljoyn_permissionconfigurator configurator, AJ_PCSTR policyXml); /** * This method allows the app to retrieve its active policy. * * @param[in] configurator The alljoyn_permissionconfigurator for the application's bus attachment. * @param[out] policyXml The active policy in XML format. This string must be freed using * alljoyn_permissionconfigurator_policy_destroy. * @return * - #ER_OK If successful. * - An error status indicating failure. */ AJ_API QStatus AJ_CALL alljoyn_permissionconfigurator_getpolicy(alljoyn_permissionconfigurator configurator, AJ_PSTR* policyXml); /** * This method allows the app to retrieve its default policy. * * @param[in] configurator The alljoyn_permissionconfigurator for the application's bus attachment. * @param[out] policyXml The default policy in XML format. This string must be freed using * alljoyn_permissionconfigurator_policy_destroy. * @return * - #ER_OK If successful. * - An error status indicating failure. */ AJ_API QStatus AJ_CALL alljoyn_permissionconfigurator_getdefaultpolicy(alljoyn_permissionconfigurator configurator, AJ_PSTR* policyXml); /** * This method deallocates strings returned by a call to alljoyn_permissionconfigurator_getdefaultpolicy * and alljoyn_permissionconfigurator_getpolicy. * * @param[in] policyXml A string containing a policy in XML format returned by a call to either * alljoyn_permissionconfigurator_getpolicy or * alljoyn_permissionconfigurator_getdefaultpolicy. */ AJ_API void AJ_CALL alljoyn_permissionconfigurator_policy_destroy(AJ_PSTR policyXml); /** * This method allows an app to remove the currently installed policy. The * application reverts back to the default policy generated during the claiming * process. * * @param[in] configurator The alljoyn_permissionconfigurator for the application's bus attachment. * * @return * - #ER_OK If successful. * - An error status indicating failure. */ AJ_API QStatus AJ_CALL alljoyn_permissionconfigurator_resetpolicy(alljoyn_permissionconfigurator configurator); /** * This method allows an app to retrieve its membership certificate summaries. * * @param[in] configurator The alljoyn_permissionconfigurator for the application's bus attachment. * @param[out] certificateIds Pointer to receive an alljoyn_certificateidarray struct containing the * serial number, issuer public key, and issuer AKI for each membership certificate. * This array must be freed by the caller with alljoyn_certificateids_destroy. * * @remarks If no membership certificates are installed, this function will return ER_OK, but certificateIds->count * will be zero. * * @return * - #ER_OK If successful. * - An error status indicating failure. */ AJ_API QStatus AJ_CALL alljoyn_permissionconfigurator_getmembershipsummaries(alljoyn_permissionconfigurator configurator, alljoyn_certificateidarray* certificateIds); /** * This method deallocates strings returned by a call to alljoyn_permissionconfigurator_getidentitycertificateid. * * @param[in] certificateIdArray Pointer to an alljoyn_certificateidarray returned from a call to * alljoyn_permissionconfigurator_getmembershipsummaries. */ AJ_API void AJ_CALL alljoyn_permissionconfigurator_certificateidarray_cleanup(alljoyn_certificateidarray* certificateIdArray); /** * This method allows the app to install a membership cert chain to itself. * * @param[in] configurator The alljoyn_permissionconfigurator for the application's bus attachment. * @param[in] membershipCertificateChain Null-terminated C string representing PEM encoded membership certificates * with the app's certificate being listed first followed by each intermediate * Certificate Authority's certificate, ending in the trusted root's certificate. * * @return * - #ER_OK If successful. * - #ER_DUPLICATE_CERTIFICATE Error raised when the membership certificate * is already installed. * - #ER_INVALID_CERTIFICATE Error raised when the membership certificate is not valid. * - An error status indicating failure. */ AJ_API QStatus AJ_CALL alljoyn_permissionconfigurator_installmembership(alljoyn_permissionconfigurator configurator, AJ_PCSTR membershipCertificateChain); /** * This method allows the app to remove a membership certificate chain from itself. * * @param[in] configurator The alljoyn_permissionconfigurator for the application's bus attachment. * @param[in] serial Certificate's serial number. * @param[in] serialLen Certificate's serial number length. * @param[in] issuerPublicKey PEM-encoded public key of the certificate's issuer. * @param[in] issuerAki Certificate issuer's AKI. * @param[in] issuerAkiLen Certificate issuer's AKI length. * * @return * - #ER_OK If successful. * - #ER_CERTIFICATE_NOT_FOUND Error raised when the membership certificate is not found. * - An error status indicating failure. */ AJ_API QStatus AJ_CALL alljoyn_permissionconfigurator_removemembership(alljoyn_permissionconfigurator configurator, const uint8_t* serial, size_t serialLen, AJ_PCSTR issuerPublicKey, const uint8_t* issuerAki, size_t issuerAkiLen); /** * This method allows the app to signal itself that management is starting. * * @param[in] configurator The alljoyn_permissionconfigurator for the application's bus attachment. * * @return * - #ER_OK If successful. * - #ER_MANAGEMENT_ALREADY_STARTED if the app is already in this state */ AJ_API QStatus AJ_CALL alljoyn_permissionconfigurator_startmanagement(alljoyn_permissionconfigurator configurator); /** * This method allows the app to signal itself that management is ending. * * @param[in] configurator The alljoyn_permissionconfigurator for the application's bus attachment. * * @return * - #ER_OK If successful. * - #ER_MANAGEMENT_NOT_STARTED if the app was not in the management state */ AJ_API QStatus AJ_CALL alljoyn_permissionconfigurator_endmanagement(alljoyn_permissionconfigurator configurator); #ifdef __cplusplus } /* extern "C" */ #endif #endif