Package: ciphertrust-sdk
ciphertrust-sdkThales CipherTrust APIInstallation>>>python-mpipinstallciphertrust-sdkUsageThis is a baseline SDK that allows you to pass the url path and parmeters for each action:GETPOSTDELETEPATCHPlease see the CipherTrust Manager Playground to see full url_paths. This will only pass the authorization and return the results as described within the documentation. It can be leveraged to handle authorization and return the work for orchestration.Creating API Authentication:fromciphertrust.apiimportAPIimportjson# User based credentialsusername="username"passwd="secretpassword"host="thales-host01.example.com"api=API(username=username,password=passwd,hostname=host,verify="/path/to/certificate.pem")response=api.get.call(url_path="vault/keys2/")print(json.dumps(response,indent=2))Sample Output:{"skip":0,"limit":10,"total":100,"resources":[{"id":"","uri":"","account":"","application":"","devAccount":"","createdAt":"","name":"","updatedAt":"","activationDate":"","state":"","usageMask":0,"meta":null,"objectType":"","sha1Fingerprint":"","sha256Fingerprint":"","defaultIV":"","version":0,"algorithm":"","size":0,"muid":""}]}CipherTrust API DocumenationKeysMethod POSTSCreate:Creates a new key
Endpoint: /v1/vault/keys2/
Required:aliasCreate Body Schema{"activationDate":string,"algorithm":string,"aliases":[{"alias":string,"index":integer,"type":string}],"archiveDate":string,"certType":string,"compromiseDate":string,"compromiseOccurrenceDate":string,"curveid":string,"deactivationDate":string,"defaultIV":string,"destroyDate":string,"format":string,"generateKeyId":boolean,"hkdfCreateParameters":{"hashAlgorithm":string,"ikmKeyName":string,"info":string,"salt":string},"id":string,"idSize":integer,"keyId":string,"macSignBytes":string,"macSignKeyIdentifier":string,"macSignKeyIdentifierType":string,"material":string,"meta":{"ownerId":string},"muid":string,"name":string,"objectType":string,"padded":boolean,"password":string,"processStartDate":string,"protectStopDate":string,"publicKeyParameters":{"activationDate":string,"aliases":[{"alias":string,"index":integer,"type":string}],"archiveDate":string,"deactivationDate":string,"meta":{},"name":string,"state":string,"undeletable":boolean,"unexportable":boolean,"usageMask":integer},"revocationMessage":string,"revocationReason":string,"rotationFrequencyDays":string,"signingAlgo":string,"size":integer,"state":string,"undeletable":boolean,"unexportable":boolean,"usageMask":integer,"uuid":string,"wrapHKDF":{"hashAlgorithm":string,"info":string,"okmLen":integer,"salt":string},"wrapIV":string,"wrapKeyIDType":string,"wrapKeyName":string,"wrapPBE":{"dklen":integer,"hashAlgorithm":string,"iteration":integer,"password":string,"passwordIdentifier":string,"passwordIdentifierType":string,"purpose":string,"salt":string},"wrapPublicKey":string,"wrapPublicKeyPadding":string,"wrappingEncryptionAlgo":string,"wrappingHashAlgo":string,"wrappingMethod":string,"xts":boolean}Export:Returns metadata and the material of the latest version of the key matching the given id and the JWT's account claim.Endpoint: /v1/vault/keys2/{id}/exportExport Body Schema{"combineXts":boolean,"format":string,"macSignKeyIdentifier":string,"macSignKeyIdentifierType":string,"padded":boolean,"password":string,"pemWrap":boolean,"signingAlgo":string,"wrapHKDF":{"hashAlgorithm":string,"info":string,"okmLen":integer,"salt":string},"wrapIV":string,"wrapJWE":{"contentEncryptionAlgorithm":string,"jwtIdentifier":string,"keyEncryptionAlgorithm":string,"keyIdentifier":string},"wrapKeyIDType":string,"wrapKeyName":string,"wrapPBE":{"dklen":integer,"hashAlgorithm":string,"iteration":integer,"password":string,"passwordIdentifier":string,"passwordIdentifierType":string,"purpose":string,"salt":string},"wrapPublicKey":string,"wrapPublicKeyPadding":string,"wrapSymmetricKeyName":string,"wrappingEncryptionAlgo":string,"wrappingHashAlgo":string,"wrappingMethod":string}Query-Keys:This operation searches for keys stored on the CipherTrust Manager. The operation is similar to the list operation. The differences are (a) a lot more search parameters can be passed in, and (b) the search parameters are passed in the body of an HTTP POST request instead of being passed as query parameters in a HTTP GET request. Normally, this operation returns a list of keys, secrets, etc., that satisfy the search criteria. When the returnOnlyIDs input parameter is specified as true, this operation just returns a list of key IDs.Query Keys Body Schema{"activationAfter":string,"activationAt":string,"activationBefore":string,"algorithm":string,"algorithms":[string],"aliases":[string],"archiveAfter":string,"archiveAt":string,"archiveBefore":string,"certFields":{"certLength":integer,"certType":string,"dsalg":string,"issuerANFields":{"dns":[string],"emailAddress":[string],"ipAddress":[string],"uri":[string]},"issuerDNFields":{"c":[string],"cn":string,"dc":[string],"dnq":[string],"email":[string],"l":[string],"o":[string],"ou":[string],"sn":string,"st":[string],"street":[string],"t":[string],"uid":[string]},"serialNumber":string,"subjectANFields":{"dns":[string],"emailAddress":[string],"ipAddress":[string],"uri":[string]},"subjectDNFields":{"c":[string],"cn":string,"dc":[string],"dnq":[string],"email":[string],"l":[string],"o":[string],"ou":[string],"sn":string,"st":[string],"street":[string],"t":[string],"uid":[string]},"x509SerialNumber":string},"compromiseAfter":string,"compromiseAt":string,"compromiseBefore":string,"compromiseOccurranceAfter":string,"compromiseOccurranceAt":string,"compromiseOccurranceBefore":string,"createdAfter":string,"createdAt":string,"createdBefore":string,"curveIDs":[string],"deactivationAfter":string,"deactivationAt":string,"deactivationBefore":string,"destroyAfter":string,"destroyAt":string,"destroyBefore":string,"id":string,"limit":integer,"linkTypes":[string],"metaContains":string,"name":string,"neverExportable":boolean,"neverExported":boolean,"objectTypes":[string],"processStartAfter":string,"processStartAt":string,"processStartBefore":string,"protectStopAfter":string,"protectStopAt":string,"protectStopBefore":string,"returnOnlyIDs":boolean,"revocationReason":string,"revocationReasons":[string],"rotationDateReached":boolean,"sha1Fingerprint":string,"sha1Fingerprints":[string],"sha256Fingerprint":string,"sha256Fingerprints":[string],"size":integer,"sizes":[integer],"skip":integer,"states":[string],"updatedAfter":string,"updatedAt":string,"updatedBefore":string,"uri":string,"usageMask":integer,"usageMasks":[integer],"version":integer,"versions":[integer]}Logging & StreamingSet up local logging for any commands exectued within this SDK for tracking and debug as well as providing readable metrics. By default there is no log file created and only logs are streamed to the console screen in a default color scheme with level set to INFO. To adjust you must provide a yaml configuration file calledciphertrust-sdk.yamlin one of two locations:<USERHOME>/.config/ciphertrust-sdk.yaml/etc/ciphertrust-sdk.yamlConfiguration File Example:LOGDIR:"/var/logs"LOGSTREAM:trueLOGSET:trueLOGNAME:"ciphertrust_sdk.log"LOGFILE:trueLOGLEVEL:"DEBUG"LOGMAXBYTES:10485760LOGBACKUPCOUNT:10If logfile is set to true without specifying aLOGDIRthe log file will check the operating system and set up the log directory in the expected default location:Windows: /tmpMacOS: ~/Library/Logs/Linux: /var/log/VersionVersionBuildChanges0.0.1finalTest Relese; basic functionality1.0.1finalAvailable Release with API and Auth functionality1.0.2a1Removed print1.0.2a2Added metrics in calls and additional awaits to call on mutliple calls1.0.2finalSee notes below1.0.3finalSee notes below1.0.4finalSee notes below1.0.5finalFixed bug passing directory param in downloads call1.0.6finalHOTFIX with generic call1.0.7hotfixFixes issues with not raising proper errors when params are being passed1.0.7featureAdjusted and tested remaining http calls; see notes for details1.0.7featureAdjusted responses for all types of API calls1.0.8a1Added Error Response handling to ensure metrics in responses and error reporting; reformated logging messages and added splunk style logs with color responses1.0.8a2Added a 30s buffer to expiration of Auth Token1.0.8a3Synced error and standard format json response under response_statistics and request_parmeters1.0.8finalFormated responses to return statatics on calls as well as data from call being made1.0.9hotfixAdded dependencies to requirements to fix installation issues1.0.10finalAdded features and adjustments for auth timeout1.0.11finalFixed issues with processing time and timezones1.0.12finalMigrated auth end and start times to epochKnown Bugs/Futue FeaturesTODO:☑ Create a metrics fucntion to return☑ Delete all private aand passwords being printed☑ Add logging or streaming or none☐ Add own metrics☐ Generic metrics wrapper☐ Logging metrics wrapper☑ Create an average, mean, total time depending on calls being made for when you want to do a full list of keys☑ Missing delete https action☑ Create a download method to handle downlaoding files☑ Error in calucation for x_processing_time for a HTTP Error code ex: error="HTTPError: 422 Client Error: Unprocessable Entity,exec_time_elapsed="-14399.518375",exec_time_end="1689378714.406082",exec_time_start="1689378713.924067",exec_time_total="-14399.518375",x_processing_time="-14399.518375"☐ Documentation states return response should be JSON, but sometimes POST will return plain/text. Need to append "Accept": "application/json" to force a json response.☐ Build out handle method for a text return if json obj is not returned.☐ remove statistics if not necessary for standard interacations.Known Bugs:Issues with usability of code, needs reformating to make both useful and return statistics.unable to get post response when decrypting data.Release Notesv1.0.16Fixed vulnerability in validators modulev1.0.14Adjusted default log location within application directory.v1.0.13Updated Requests Library dependencies.v1.0.12Changed Start/End auth times to epoch.Updated requirements file.Added Iterations tracking in auth.v1.0.11Fixed issue with error returning negative processing time.v1.0.10Increased the length of time for a token by decresing the value used to compare the token is still valid from 30s to 15s.Addedexpiration_offsetto AuthParams which is called in Auth class to allow for adjusting the token offset.Value is set for float, but could take int.Cannot use a negative number as that will cause an issue.Migrated to use current time and convert to GMT when necessary.Bug Fix:Fixed issue with Auth where there was an incorrect comparison in auth token forcing a creation of a new token each call.Adjusted time being returned to local time vs UTC.v1.0.9Bug Fix:Fixed dependency issue.v1.0.8Changed all timestamps to utc epoch float.Updated formatting of logging.Added easy_logger to help processs on screen and rotating log formats.Added configuration for logger through a yaml configuration file.Sets a default logger configuration if one isn't supplied in a config location area.v1.0.7Issues when parsing response depending on call done with GET due to parameters not being stripped out.Created a RequestParam that strips out any additional variable arguments getting passed to avoid this issue.Added error handling to ensure that proper error response is reported when issue occurs.Raises local class CipherTrust Exceptions.Issues with PATCH, POST, and DELETE HTTP Operations due to how CipherTrust responds and how the SDK expected a response back.Adjusted how each call is handled stripping out unnecessary params only passing the proper ones.Adjusted how responses that are OK without any content are reorganized and responded to.CipherTrust responds with Zulu based time; so adjusted the response times on the API calls to follow suite.Due to this all exec_time_end and exec_time_start times need to be parsed and converted properly to be able to make correct time calls.Adjusted requests.headers response to ensure no Dict issues are raised.Added status code to response to bundle into the response as with the different calls there are different OK codes that can designate the proper changes.Removed raising HTTP Error or CipherTrustAPI Error and send back an error message response for digestion on the other side.v1.0.6HOTFIXIssue with sandard get call passes invalid arg to response.TODO:Need to build additional async requests when calling multiple items.Build out ability to send multiple requests and hold the type of requests to make it easier to use the SDK.v1.0.5Bug fixed with passing "save_dir" into get call for downloading log files.v1.0.4Updated standard download log file to include hostname in filename.v1.0.3Fixed bug with headers returning a requests.exceptions.JSONDecodeError due to the way headers are formated.Added more timeing metrics for quanitfying calls.Added ability to request a download when stream=True is passed in call.v1.0.2Added Generic Metrics to each call with additional statistics that can be used.Added async to handle multle requests; still need to take advantage of it.Removed disclosure of secrets in debug prints.Known Bugs:Too many calls cause crash or non-responsive requests leading to time out.v1.0.1Initial usable releaseAllows ability to run get functions in a wrapper.Supply all changes and updates with the standard get request using the api.get() call.ChangelogIssues with CipherTrustv2.7that made a change in the backend database and how refresh tokens are handled. Since they are not deleted and infinite they are filling up servers causing them to become unresponsive.This is fixed in upcoming releases.Updated code to enforceauthrefresh if therefresh_token_lifetimeis set.Ifrefresh_token_lifetimeis not set the default is0which is infinite.TODO:Add a way to monitor the passage ofrefresh_token_revoke_unused_inas that timmer can revoke a token if it is not used after a period of time.It is recommended to set the parameters accordingly as to not fill up the database with unusable tokens.