Features to implement

[gdbarron]

Hi all. I'm interested in implementing features which will be most useful to folks. Please let me know your thoughts! The SDK can be found https://docs.venafi.com/Docs/18.1SDK/TopNav/Content/SDK/WebSDK/API_Reference/c-REST-API-reference.php?tocpath=REST%20API%20reference%7C_____0.

@BeardedPrincess, mind chiming in?

[BeardedPrincess]

@gdbarron I poked around in my library of scripts that I've written and come up with a list of functions that I've re-used frequently. Hope this helps!

Get-TPPConfigAttribute (looks like this is probably done)

Set-TPPConfigAttribute

Get-TPPCustomFieldGUID

• returns the GUID of a custom field, so that it can be set using Set-TPPConfigAttribute
• There are a couple of ways this can be done, one consideration would be to make a single call to get them all at once, and store them in a hashtable and reference them later. (POST metadata/getitemsforclass)
• You could extend the config read/write with a switch param that tells those functions that what is being set is a custom field

Rename-TPPConfigObject

• Moves or renames a config object

Find-TPPCertificate

• Leverages GET /certificates and a long list of parameters to match the API function

Test-TPPObjectExists

• Uses /config/IsValid to check if an object DN or GUID exists

Get-TPPVersion

• I can help with this one. It's handy to know what TPP version you're hitting to know what functions are available

New-TPPConfigObject

• Uses /config/create to create new objects that aren't certificates (like devices, applications, etc)

Net-TPPCertificateAssociation

• Creates the association between certificate object and application object. (Since this is more complex than a simply config/write)

Get-TPPWorkflowTickets

• Uses POST /workflow/ticket/enumerate to return list of workflow tickets pending for current user

Get-TPPWorkflowTicketDetail

• Returns detail for workflow ticket (POST /workflow/ticket/details)
• Accepting pipleline input would be cool here

Set-TPPWorkflowTicketApproved

• Approves workflow ticket (POST workflow/ticket/updatestatus)

Set-TPPWorkflowTicketRejected

• Approves workflow ticket (POST workflow/ticket/updatestatus)

[gdbarron]

@BeardedPrincess, this is great. Much appreciated!

You mentioned helping with Get-TppVersion so I created a new issue for that one. If/when you have time, let me know.

[wilddev65]

I'll add a couple I've used as well;
Get-TPPObjectClass

• Uses Config/FindObjectsOfClass to find objects of a specific class and return the DN
  Test-CSVFile
• A generic test to see if a CSV has the correct columns and has rows for bulk operations

[gdbarron]

Thanks, @wilddev65! I've added an issue for Get-TppConfigObject, #11.

[gdbarron]

@wilddev65, I've added Get-TppObject which allows you to get an object either by class or pattern.

[Saadi6]

@gdbarron Thank you for adding Get-TppPermission.

I think a function for setting permissions should incorporate few checks to prevent unintentional changes because the level of access a user has to objects in TPP underpins the functions they can perform in the GUI.

This may be split into two or more functions for better usability.

Set-TppPermission
Sets new or updates existing permission on an object while considering the following:

• Uses POST Permissions to set new permissions when explicit permissions on the object for this identity does not exist.
• Uses PUT Permissions to update permissions when explicit permissions on the object for this identity exists.
• A switch indicates whether all existing explicit permissions for this identity are removed before setting new permissions. This calls another function to delete permissions for this identity when they exist.
• Implicit (inherited) IsManagePermissionsAllowed is not over ridden by a lesser explicit permission for this identity unless confirmed with a switch.
• If this identity already has any implicit (inherited) permission on this object then a switch confirms explicit permissions should be set anyway.
• Parse the set of permission strings to ensure they match names in TPP documentation.

[mlamutt]

Hi all,
First off, thanks for this great module. There are a lot of good functions here. I am looking to add a disassociate a certificate from an application, and a delete certificate function. Does any of the existing functions cover these 2 requests? If not it looks like it would be fairly straight forward to adding them.

https://docs.venafi.com/Docs/18.2SDK/TopNav/Content/SDK/WebSDK/API_Reference/r-SDK-POST-Certificates-Dissociate.php?Highlight=remove%20from%20application

https://docs.venafi.com/Docs/18.2SDK/TopNav/Content/SDK/WebSDK/API_Reference/r-SDK-DELETE-Certificates-Guid.php?Highlight=delete%20certificate

thanks

[Saadi6]

Delete Certificates/{guid} is a little heavy handed if all you wish to do is remove application and device association from a certificate. Use the Certificates/Dissociate for this purpose. This method allows you to optionally remove the device and application objects if they have been orphaned i.e. the same device object is not associated with another certificate.

If a Delete Certificate function is added then a Dissociate Certificate function should also be added at the same time. Delete function may have an additional safety to check for an association. A switch confirms certificate objects with associations should be deleted.

Note that neither Delete nor Dissociate method removes the Device object if it has other associations, which is handy.

cheers.

[mlamutt]

@Saadi6 I agree with all your statements. The Delete Certificate is for a specific use case, in our case a website has been decommissioned, and we are purging the full config, from the code base, load balancer config, cert , etc.. In most cases we move the cert to an archive folder that is not monitored after it has been dissociated from all applications.

[gdbarron]

Thanks guys. I'm working on finalizing permission updates and then will have a look at dissociate and delete cert. @mlamutt, would you mind creating a new issue for this?

[tristanbarcelon]

@gdbarron , first off, thank you for this very useful module. I've been using it to obtain metadata about our certs in Venafi, but lately I have a need to actually download the certificate file (in pem or pfx) to the file system. My plan is to use this download feature to fetch a code signing or an SSL cert during build or deployment from Venafi, install it on the target, and then wipe the file. Would you be open to a PR which uses the /vedsdk/certificates/Retrieve endpoint to download the certificate file by using its distinguished name? From the looks of it, it appears I could use the Get-TppCertificateDetail to search by CommonName and obtain the distinguished name. If an entry is found, then use the /vedsdk/certificates/retrieve endpoint. If more than 1 entry is found, I suppose it could just throw a warning rather than fetch all of them.

UPDATE I just realized that Invoke-TPPRestMethod mostly returns JSON objects and has no means for me to inject the OutFile parameter to either Invoke-RestMethod or Invoke-WebRequest cmdlets. PFX is binary so I'm not sure how I'm going to be able to persist it. I'll need a little bit more time to research an alternative method.

[Saadi6]

@tristanbarcelon suggested function is useful.

Certificate/Retrieve will return the X.509 certificate on its own or with a Private Key if present in TPP. Including private key forces use of a password. Instead of generating a password in your function, I suggest making it a mandatory parameter when private key is to be included - same as how Certificate/Retrieve works. The password for the private key should not touch disk in clear text.

Certificate/Retrieve supports the most common containers such as JKS, PKCS or raw cert data.

As an aside - Certificate/Retrieve does not support KeePass, which is commonly used by IBM's applications. I believe IBM uses v1 of KeePass which has KDB file extension. I baked-on support for KDB by retrieving in PKCS format from Certificate/Retrieve then converting to KDB using a utility from IBM's GSKit. The function then emails the KDB or writes it to disk and returns the file's location. GSKit is proprietary but I came across this recently https://github.com/PSKeePass/PoShKeePass. Might be worth looking into for future...

Regards.

[gdbarron]

@tristanbarcelon, thanks for your suggestion and as @Saadi6 says it will definitely be useful. What good is a certificate management module if you can't get a cert? :) I'm definitely open to you working on this. Can you please create a new Issue for this enhancement and assign it to yourself?

There shouldn't be any issues with using Invoke-TppRestMethod as is...I don't think. I've put a sample in a new branch for you to have a look. It doesn't use -OutFile, but rather does a base64 conversion of the certificate data.

[gdbarron]

Most of the suggestions here have been implemented. Any new enhancements can be entered as a new issue.