{ "info": { "author": "Microsoft Corporation", "author_email": "azurekeyvault@microsoft.com", "bugtrack_url": null, "classifiers": [ "Development Status :: 4 - Beta", "License :: OSI Approved :: MIT License", "Programming Language :: Python", "Programming Language :: Python :: 2", "Programming Language :: Python :: 2.7", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.5", "Programming Language :: Python :: 3.6", "Programming Language :: Python :: 3.7" ], "description": "# Azure Key Vault Certificates client library for Python\nAzure Key Vault helps solve the following problems:\n- Certificate management (this library) - create, manage, and deploy public and private SSL/TLS certificates\n- Cryptographic key management\n([`azure-keyvault-keys`](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/keyvault/azure-keyvault-keys)) - create, store, and control access to the keys used to encrypt your data\n- Secrets management\n([`azure-keyvault-secrets`](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/keyvault/azure-keyvault-secrets)) -\nsecurely store and control access to tokens, passwords, certificates, API keys,\nand other secrets\n\n[Source code][certificates_client_src] | [Package (PyPI)][pypi_package_certificates] | [API reference documentation][reference_docs] | [Product documentation][keyvault_docs] | [Samples][certificates_samples]\n\n## Getting started\n### Install the package\nInstall the Azure Key Vault client library for Python with [pip][pip]:\n\n```Bash\npip install azure-keyvault-certificates\n```\n\n### Prerequisites\n* An [Azure subscription][azure_sub]\n* Python 2.7, 3.5.3, or later\n* A Key Vault. If you need to create one, you can use the\n[Azure Cloud Shell][azure_cloud_shell] to create one with these commands\n(replace `\"my-resource-group\"` and `\"my-key-vault\"` with your own, unique\nnames):\n * (Optional) if you want a new resource group to hold the Key Vault:\n ```sh\n az group create --name my-resource-group --location westus2\n ```\n * Create the Key Vault:\n ```Bash\n az keyvault create --resource-group my-resource-group --name my-key-vault\n ```\n\n Output:\n ```json\n {\n \"id\": \"...\",\n \"location\": \"westus2\",\n \"name\": \"my-key-vault\",\n \"properties\": {\n \"accessPolicies\": [...],\n \"createMode\": null,\n \"enablePurgeProtection\": null,\n \"enableSoftDelete\": null,\n \"enabledForDeployment\": false,\n \"enabledForDiskEncryption\": null,\n \"enabledForTemplateDeployment\": null,\n \"networkAcls\": null,\n \"provisioningState\": \"Succeeded\",\n \"sku\": { \"name\": \"standard\" },\n \"tenantId\": \"...\",\n \"vaultUri\": \"https://my-key-vault.vault.azure.net/\"\n },\n \"resourceGroup\": \"my-resource-group\",\n \"type\": \"Microsoft.KeyVault/vaults\"\n }\n ```\n\n > The `\"vaultUri\"` property is the `vault_endpoint` used by `CertificateClient`\n\n### Authenticate the client\nIn order to interact with a Key Vault's certificates, you'll need an instance\nof the [CertificateClient][certificate_client_docs] class. Creating one\nrequires a **vault url** and **credential**. This document demonstrates using\n`DefaultAzureCredential` as the credential, authenticating with a service\nprincipal's client id, secret, and tenant id. Other authentication methods are\nsupported. See the [azure-identity][azure_identity] documentation for more\ndetails.\n\n#### Create a service principal\nThis [Azure Cloud Shell][azure_cloud_shell] snippet shows how to create a\nnew service principal. Before using it, replace \"your-application-name\" with\na more appropriate name for your service principal.\n\n * Create a service principal:\n ```Bash\n az ad sp create-for-rbac --name http://my-application --skip-assignment\n ```\n Output:\n ```json\n {\n \"appId\": \"generated app id\",\n \"displayName\": \"my-application\",\n \"name\": \"http://my-application\",\n \"password\": \"random password\",\n \"tenant\": \"tenant id\"\n }\n ```\n\n * Use the output to set **AZURE_CLIENT_ID** (appId), **AZURE_CLIENT_SECRET**\n(password) and **AZURE_TENANT_ID** (tenant) environment variables. The\nfollowing example shows a way to do this in Bash:\n ```Bash\n export AZURE_CLIENT_ID=\"generated app id\"\n export AZURE_CLIENT_SECRET=\"random password\"\n export AZURE_TENANT_ID=\"tenant id\"\n ```\n\n* Authorize the service principal to perform certificate operations in your Key Vault:\n ```Bash\n az keyvault set-policy --name my-key-vault --spn $AZURE_CLIENT_ID --certificate-permissions backup create delete get import list purge recover restore update\n ```\n > Possible certificate permissions: backup, create, delete, deleteissuers, get, getissuers, import, list, listissuers, managecontacts, manageissuers, purge, recover, restore, setissuers, update\n\n#### Create a client\nAfter setting the **AZURE_CLIENT_ID**, **AZURE_CLIENT_SECRET** and\n**AZURE_TENANT_ID** environment variables, you can create the [CertificateClient][certificate_client_docs]:\n\n```python\nfrom azure.identity import DefaultAzureCredential\nfrom azure.keyvault.certificates import CertificateClient\n\ncredential = DefaultAzureCredential()\n\n# Create a new certificate client using the default credential\ncertificate_client = CertificateClient(vault_endpoint=, credential=credential)\n```\n## Key concepts\nWith a `CertificateClient` you can get certificates from the vault, create new certificates and\nnew versions of existing certificates, update certificate metadata, and delete certificates. You\ncan also manage certificate issuers, contacts, and management policies of certificates. This is\nillustrated in the [examples](#examples) below.\n\n### Certificate\n A certificate is the fundamental resource within Azure KeyVault. From a developer's perspective,\n Key Vault APIs accept and return certificates as the Certificate type. In addition to the\n certificate data, the following attributes may be specified:\n* expires: Identifies the expiration time on or after which the certificate data should not be retrieved.\n* not_before: Identifies the time after which the certificate will be active.\n* enabled: Specifies whether the certificate data can be retrieved.\n* created: Indicates when this version of the certificate was created.\n* updated: Indicates when this version of the certificate was updated.\n\n### Certificate Client:\n\n## Examples\nThis section contains code snippets covering common tasks:\n* [Create a Certificate](#create-a-certificate)\n* [Retrieve a Certificate](#retrieve-a-certificate)\n* [Update an existing Certificate](#update-an-existing-certificate)\n* [Delete a Certificate](#delete-a-certificate)\n* [List Certificates](#list-certificates)\n* [Asynchronously create a Certificate](#asynchronously-create-a-certificate)\n* [Asynchronously list certificates](#asynchronously-list-certificates)\n\n### Create a Certificate\n`create_certificate` creates a Certificate to be stored in the Azure Key Vault. If a certificate with\nthe same name already exists, then a new version of the certificate is created.\nBefore creating a certificate, a management policy for the certificate can be created or our default\npolicy will be used. The `create_certificate` operation returns a long running operation poller.\n```python\ncreate_certificate_poller = certificate_client.create_certificate(name=\"cert-name\")\n\nprint(create_certificate_poller.result())\n```\n\n### Retrieve a Certificate\n`get_certificate_with_policy` retrieves a certificate previously stored in the Key Vault without\nhaving to specify version.\n```python\ncertificate = certificate_client.get_certificate_with_policy(name=\"cert-name\")\n\nprint(certificate.name)\nprint(certificate.properties.version)\nprint(certificate.policy.id)\n```\n\n`get_certificate` retrieves a certificate based on the certificate name and the version of the certificate.\nVersion is required.\n```python\ncertificate = certificate_client.get_certificate(name=\"cert-name\", version=\"cert-version\")\n\nprint(certificate.name)\nprint(certificate.properties.version)\n```\n\n### Update an existing Certificate\n`update_certificate` updates a certificate previously stored in the Key Vault.\n```python\n# You can specify additional application-specific metadata in the form of tags.\ntags = {\"foo\": \"updated tag\"}\n\nupdated_certificate= certificate_client.update_certificate_properties(name=\"cert-name\", tags=tags)\n\nprint(updated_certificate.name)\nprint(updated_certificate.properties.version)\nprint(updated_certificate.properties.updated)\nprint(updated_certificate.properties.tags)\n\n```\n\n### Delete a Certificate\n`delete_certificate` deletes a certificate previously stored in the Key Vault. When [soft-delete][soft_delete]\nis not enabled for the Key Vault, this operation permanently deletes the certificate.\n```python\ndeleted_certificate = certificate_client.delete_certificate(name=\"cert-name\")\n\nprint(deleted_certificate.name)\nprint(deleted_certificate.deleted_date)\n```\n### List Certificates\nThis example lists all the certificates in the specified Key Vault.\n```python\ncertificates = certificate_client.list_certificates()\n\nfor certificate in certificates:\n # this list doesn't include versions of the certificates\n print(certificate.name)\n```\n\n### Async operations\nThis library includes a complete async API supported on Python 3.5+. To use it, you must\nfirst install an async transport, such as [`aiohttp`](https://pypi.org/project/aiohttp/).\nSee\n[azure-core documentation](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/core/azure-core/README.md#transport)\nfor more information.\n\n### Asynchronously create a Certificate\n`create_certificate` creates a Certificate to be stored in the Azure Key Vault. If a certificate with the\nsame name already exists, then a new version of the certificate is created.\nBefore creating a certificate, a management policy for the certificate can be created or our default policy\nwill be used. The `create_certificate` operation returns an async long running operation poller.\n```python\ncreate_certificate_poller = await certificate_client.create_certificate(name=\"cert-name\")\n\ncreate_certificate_result = await create_certificate_poller\nprint(create_certificate_result)\n```\n\n### Asynchronously list certificates\nThis example lists all the certificates in the client's vault:\n```python\ncertificates = certificate_client.list_certificates()\n\nasync for certificate in certificates:\n print(certificate.name)\n```\n\n## Troubleshooting\n### General\nKey Vault clients raise exceptions defined in [`azure-core`][azure_core_exceptions].\n\nFor example, if you try to retrieve a certificate after it is deleted a `404` error is returned, indicating\nresource not found. In the following snippet, the error is handled gracefully by catching the exception and\ndisplaying additional information about the error.\n```python\nfrom azure.core.exceptions import ResourceNotFoundError\ntry:\n certificate_client.get_certificate(name=\"deleted_certificate\", version=\"deleted_certificate_version\")\nexcept ResourceNotFoundError as e:\n print(e.message)\n\nOutput: \"certificate not found:deleted_certificate\"\n```\n### Logging\nNetwork trace logging is disabled by default for this library. When enabled,\nHTTP requests will be logged at DEBUG level using the `logging` library. You\ncan configure logging to print debugging information to stdout or write it\nto a file:\n\n ```python\nimport sys\nimport logging\n\n # Create a logger for the 'azure' SDK\nlogger = logging.getLogger(__name__)\nlogger.setLevel(logging.DEBUG)\n\n # Configure a console output\nhandler = logging.StreamHandler(stream=sys.stdout)\nlogger.addHandler(handler)\n\n # Configure a file output\nfile_handler = logging.FileHandler(filename)\nlogger.addHandler(file_handler)\n\n# Enable network trace logging. Each HTTP request will be logged at DEBUG level.\nclient = CertificateClient(vault_endpoint=url, credential=credential, logging_enable=True))\n```\n\nNetwork trace logging can also be enabled for any single operation:\n ```python\ncertificate = certificate_client.get_certificate_with_policy(name=\"cert-name\", logging_enable=True)\n```\n\n## Next steps\nSeveral samples are available in the Azure SDK for Python GitHub repository. These samples provide example code for additional Key Vault scenarios:\n* [test_examples_certificates.py][test_example_certificates] and\n[test_examples_certificates_async.py][test_example_certificates_async] - code snippets from\nthe library's documentation\n* [hello_world.py][hello_world_sample] and [hello_world_async.py][hello_world_async_sample] - create/get/update/delete certificates\n* [backup_restore_operations.py][backup_operations_sample] and [backup_restore_operations_async.py][backup_operations_async_sample] - backup and\nrecover certificates\n\n ### Additional Documentation\nFor more extensive documentation on Azure Key Vault, see the [API reference documentation][reference_docs].\n\n## Contributing\nThis project welcomes contributions and suggestions. Most contributions require\nyou to agree to a Contributor License Agreement (CLA) declaring that you have\nthe right to, and actually do, grant us the rights to use your contribution.\nFor details, visit https://cla.microsoft.com.\n\nWhen you submit a pull request, a CLA-bot will automatically determine whether\nyou need to provide a CLA and decorate the PR appropriately (e.g., label,\ncomment). Simply follow the instructions provided by the bot. You will only\nneed to do this once across all repos using our CLA.\n\nThis project has adopted the\n[Microsoft Open Source Code of Conduct][code_of_conduct]. For more information,\nsee the Code of Conduct FAQ or contact opencode@microsoft.com with any\nadditional questions or comments.\n\n[asyncio_package]: https://docs.python.org/3/library/asyncio.html\n[azure_cloud_shell]: https://shell.azure.com/bash\n[azure_core_exceptions]: https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/core/azure-core/docs/exceptions.md\n[azure_identity]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/identity/azure-identity\n[azure_sub]: https://azure.microsoft.com/free/\n[code_of_conduct]: https://opensource.microsoft.com/codeofconduct/\n[backup_operations_sample]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/keyvault/azure-keyvault-certificates/samples/backup_restore_operations.py\n[backup_operations_async_sample]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/keyvault/azure-keyvault-certificates/samples/backup_restore_operations_async.py\n[hello_world_sample]: https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/keyvault/azure-keyvault-certificates/samples/hello_world.py\n[hello_world_async_sample]: https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/keyvault/azure-keyvault-certificates/samples/hello_world_async.py\n[certificate_client_docs]: https://azure.github.io/azure-sdk-for-python/ref/azure.keyvault.certificates.html#azure.keyvault.certificates.CertificateClient\n[keyvault_docs]: https://docs.microsoft.com/en-us/azure/key-vault/\n[list_operations_sample]: https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/keyvault/azure-keyvault-certificates/samples/list_operations.py\n[pip]: https://pypi.org/project/pip/\n[pypi_package_certificates]: https://pypi.org/project/azure-keyvault-certificates/\n[reference_docs]: https://azure.github.io/azure-sdk-for-python/ref/azure.keyvault.certificates.html\n[certificates_client_src]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/keyvault/azure-keyvault-certificates/azure/keyvault/certificates\n[certificates_samples]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/keyvault/azure-keyvault-certificates/samples\n[soft_delete]: https://docs.microsoft.com/en-us/azure/key-vault/key-vault-ovw-soft-delete\n[test_example_certificates]: https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/keyvault/azure-keyvault-certificates/tests/test_examples_certificates.py\n[test_example_certificates_async]: https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/keyvault/azure-keyvault-certificates/tests/test_examples_certificates_async.py\n\n![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-python%2Fsdk%2Fkeyvault%2Fazure-keyvault-certificates%2FFREADME.png)\n\n\n# Release History\n\n## 4.0.0b4 (2019-10-08)\n### Breaking changes\n- Enums `JsonWebKeyCurveName` and `JsonWebKeyType` have been renamed to `KeyCurveName` and `KeyType`, respectively.\n- Both async and sync versions of `create_certificate` now return pollers that return the created `Certificate` if creation is successful,\nand a `CertificateOperation` if not.\n- `Certificate` now has attribute `properties`, which holds certain properties of the\ncertificate, such as `version`. This changes the shape of the `Certificate` type,\nas certain properties of `Certificate` (such as `version`) have to be accessed\nthrough the `properties` property. See the updated [docs](https://azure.github.io/azure-sdk-for-python/ref/azure.keyvault.certificates.html)\nfor details.\n- `update_certificate` has been renamed to `update_certificate_properties`\n- The `vault_url` parameter of `CertificateClient` has been renamed to `vault_endpoint`\n- The property `vault_url` has been renamed to `vault_endpoint` in all models\n\n## 4.0.0b3 (2019-09-11)\nVersion 4.0.0b3 is the first preview of our efforts to create a user-friendly and Pythonic client library for Azure Key Vault's certificates.\n\n This library is not a direct replacement for `azure-keyvault`. Applications\nusing that library would require code changes to use `azure-keyvault-certificates`.\nThis package's\n[documentation](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/keyvault/azure-keyvault-certificates/README.md)\nand\n[samples](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/keyvault/azure-keyvault-certificates/samples)\ndemonstrate the new API.\n\n### Breaking changes from `azure-keyvault`:\n- Packages scoped by functionality\n - `azure-keyvault-certificates` contains a client for certificate operations\n- Client instances are scoped to vaults (an instance interacts with one vault\nonly)\n- Authentication using `azure-identity` credentials\n - see this package's\n [documentation](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/keyvault/azure-keyvault-keys/README.md)\n , and the\n [Azure Identity documentation](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/identity/azure-identity/README.md)\n for more information\n\n### New Features:\n- Distributed tracing framework OpenCensus is now supported\n- Asynchronous API supported on Python 3.5.3+\n - the `azure.keyvault.certificates.aio` namespace contains an async equivalent of\n the synchronous client in `azure.keyvault.certificates`\n - Async clients use [aiohttp](https://pypi.org/project/aiohttp/) for transport\n by default. See [azure-core documentation](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/core/azure-core/README.md/#transport)\n for more information about using other transports.\n\n\n", "description_content_type": "text/markdown", "docs_url": null, "download_url": "", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/keyvault/azure-keyvault-certificates", "keywords": "", "license": "MIT License", "maintainer": "", "maintainer_email": "", "name": "azure-keyvault-certificates", "package_url": "https://pypi.org/project/azure-keyvault-certificates/", "platform": "", "project_url": "https://pypi.org/project/azure-keyvault-certificates/", "project_urls": { "Homepage": "https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/keyvault/azure-keyvault-certificates" }, "release_url": "https://pypi.org/project/azure-keyvault-certificates/4.0.0b4/", "requires_dist": [ "azure-core (<2.0.0,>=1.0.0b2)", "azure-common (~=1.1)", "msrest (>=0.5.0)", "azure-keyvault-nspkg ; python_version<'3.0'", "enum34 (>=1.0.4) ; python_version<'3.4'", "typing ; python_version<'3.5'" ], "requires_python": "", "summary": "Microsoft Azure Key Vault Certificates Client Library for Python", "version": "4.0.0b4" }, "last_serial": 5946481, "releases": { "4.0.0b3": [ { "comment_text": "", "digests": { "md5": "c2415f410ab9c508fe8864f145c401df", "sha256": "8160706a6d1fd1cc1146ccafbe5d7d72b5c69d9ed6fc33564620c5320da5d626" }, "downloads": -1, "filename": "azure_keyvault_certificates-4.0.0b3-py2.py3-none-any.whl", "has_sig": false, "md5_digest": "c2415f410ab9c508fe8864f145c401df", "packagetype": "bdist_wheel", "python_version": "py2.py3", "requires_python": null, "size": 167075, "upload_time": "2019-09-11T17:53:34", "url": "https://files.pythonhosted.org/packages/d1/1e/793db0593d11fd594127ac2c43cab31173c1c588f476e4e8bf13cf59f151/azure_keyvault_certificates-4.0.0b3-py2.py3-none-any.whl" }, { "comment_text": "", "digests": { "md5": "e51d153d2e9854ecb1e689f0521d2db2", "sha256": "cceb84c7d2976a180cfdd82cce6da2fac0e7da892a391cc5aa90882979993824" }, "downloads": -1, "filename": "azure-keyvault-certificates-4.0.0b3.zip", "has_sig": false, "md5_digest": "e51d153d2e9854ecb1e689f0521d2db2", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 188000, "upload_time": "2019-09-11T17:53:37", "url": "https://files.pythonhosted.org/packages/d4/94/fdd24f930a030f3d9af801de5b64fed318465869435da7986d3a729117c6/azure-keyvault-certificates-4.0.0b3.zip" } ], "4.0.0b4": [ { "comment_text": "", "digests": { "md5": "a52100b9617aa570cc5d76db5cf091df", "sha256": "c2e62cd288eaec067d8b0671cba01be4c7f89b661f9886226b975a9ecba898b8" }, "downloads": -1, "filename": "azure_keyvault_certificates-4.0.0b4-py2.py3-none-any.whl", "has_sig": false, "md5_digest": "a52100b9617aa570cc5d76db5cf091df", "packagetype": "bdist_wheel", "python_version": "py2.py3", "requires_python": null, "size": 167950, "upload_time": "2019-10-08T20:17:00", "url": "https://files.pythonhosted.org/packages/0e/0f/4696b44ec8936f2bea5654b85bccf51210374d35a207814676d8f6daecc4/azure_keyvault_certificates-4.0.0b4-py2.py3-none-any.whl" }, { "comment_text": "", "digests": { "md5": "0ea3470ee8dcfdc32718efef7dbbc805", "sha256": "6efdcc43909d78d264bbcc60b3307e0647e8af1ad9bb798161cbcb00e4fe24d5" }, "downloads": -1, "filename": "azure-keyvault-certificates-4.0.0b4.zip", "has_sig": false, "md5_digest": "0ea3470ee8dcfdc32718efef7dbbc805", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 655833, "upload_time": "2019-10-08T20:17:02", "url": "https://files.pythonhosted.org/packages/25/12/d7987d4a17d1cccb5a608d8d1f615962eff3998a91c77a1063845fe54792/azure-keyvault-certificates-4.0.0b4.zip" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "a52100b9617aa570cc5d76db5cf091df", "sha256": "c2e62cd288eaec067d8b0671cba01be4c7f89b661f9886226b975a9ecba898b8" }, "downloads": -1, "filename": "azure_keyvault_certificates-4.0.0b4-py2.py3-none-any.whl", "has_sig": false, "md5_digest": "a52100b9617aa570cc5d76db5cf091df", "packagetype": "bdist_wheel", "python_version": "py2.py3", "requires_python": null, "size": 167950, "upload_time": "2019-10-08T20:17:00", "url": "https://files.pythonhosted.org/packages/0e/0f/4696b44ec8936f2bea5654b85bccf51210374d35a207814676d8f6daecc4/azure_keyvault_certificates-4.0.0b4-py2.py3-none-any.whl" }, { "comment_text": "", "digests": { "md5": "0ea3470ee8dcfdc32718efef7dbbc805", "sha256": "6efdcc43909d78d264bbcc60b3307e0647e8af1ad9bb798161cbcb00e4fe24d5" }, "downloads": -1, "filename": "azure-keyvault-certificates-4.0.0b4.zip", "has_sig": false, "md5_digest": "0ea3470ee8dcfdc32718efef7dbbc805", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 655833, "upload_time": "2019-10-08T20:17:02", "url": "https://files.pythonhosted.org/packages/25/12/d7987d4a17d1cccb5a608d8d1f615962eff3998a91c77a1063845fe54792/azure-keyvault-certificates-4.0.0b4.zip" } ] }