Skip to main content
Version: 3.22

Certificate Management Methods

caution

To use these methods the Certificates resource must be selected in the application authorization.

Introduction

The senhasegura Certificate Management provide centralized management of the digital certificate lifecycle within the organization, from Discovery through automatic scanning of websites, directories and web servers, to automated Certificate renewal through external or internal Certificate Authorities.

The purpose of this document is to provide guidance for users using Certificate Management administrator roles, and to discuss details about their use, benefits, concepts, and procedures.

How the Certificate Management works

senhasegura Certificate Management manages the entire digital Certificate lifecycle, working with Certificate through request generation, manual importation of existing Certificates, or Discovery of Certificates across Devices, Domains or Containers. In addition to monitoring certificate validity and facilitating renewal, Certificate Management also allows you to view logs and reports on all operations performed through the solution.

Definitions

The senhasegura uses specific terminology for its functions and features. Thus, some terms must be understood before starting to use the solution:

  • User: Own employees, interns or third parties who use or may need access to company systems;

  • Digital Certificate: Digital certificates are files that contain public and private key information that is used for secure communication over the Internet, as well as to certify the sender's authenticity

  • Certification Authority: Certification Authority is an entity duly registered with the responsible bodies and which has the function of issuing digital certificates.

Activities

In this section, the following passwords functions will be covered: make requests, receive answers and senhasegura Certificate Management method.

Method

The senhasegura integration webservice has some methods to query, create or change information stored in the application.

Create / Modify a Request

POST https://vault_url/iso/certificate/request/\[request_code\] 

The Create / Modify Request method creates or modifies a certificate request in senhasegura

Parameters

FieldTypeDescriptionRequired
code_requestIntCode of an already created request. If the code is not included in the parameter, a new Request will be created.No
certificate_typeIntType of certificate. The possible values are:
1 = DV SSL - Domain SSL;
2 = OV SSL - Organization SSL;
3 = EV SSL - Extended SSLYes
domain_typeStringType of the certificate domain. The possible values are:
SING = Single domain
MULT = Multiple domains
WILD = WildcardYes
organizationIntCode of the organization. The code of an organization registered in passwords must be informed.Yes
common_nameStringCertificate common nameYes
sanArraySubject Alternative Name. It will be filled with common_name if san is not informed.No
tagsArrayCertificate identification tags. New tags will be registered if the reported ones do not existNo
encryptionStringencryption. The possible values are: RSA
DSAYes
encryption_key_sizeIntSize of the encryption key. The possible values are:
4096
2048
1024Yes
certificate_algorithmStringSignature Algorithm. The possible values are:
SHA256
SHA384
SHA512
If the encryption chosen is DSA, then only SHA256 may be used.Yes
validityIntCertificate validity time, in days.Yes
key_passwordStringPassword if the certificate key.No
password_revogationStringCertificate revocation password.No
environmentsArrayCertificate environments. New certificate environments will be registered if the informed ones do not exist.No
systemsArrayCertificate systems. New certificate systems will be registered if the informed ones do not exist.No
projectStringCertificate project in request.No
external_ipStringExternal IP of the certificate in the request.No
hostname_ipStringIP or certificate hostname in request.No
justificationStringRequest justification of up to 1024 characters.No
responsibleIntCode of the requester and the certificate. Must be a registered username account in senhasegura .No
descriptionStringDescription of the request up to 512 characters.No

Response to certificates

If the method succeeds or fails, the response consists of a certified block with the fields:

FieldTypeSuccessError
statusInt, for certificate creation
200, for certificate editing4xx
messageTextCreated for certificate creation
OK, for certificate editingCould not create request
errorN/Afalsetrue
code_requestIntRequest code.The request code entered is invalid
type_certifiedIntType of the entered certificate.The certificate type you entered is invalid.
type_domainStringType of certificate domain entered.The certificate domain type you entered is invalid.
organizationIntOrganization code entered.The organization code you entered is invalid
common_nameStringCommon name entered.Certificate common name not entered
sanArraySAN informed.
tagsArrayTags informed.
encryptionStringEncryption Algorithm entered.Encryption algorithm entered is invalid
encryption_key_sizeIntSize of encryption key entered.The encryption key length entered is invalid.
certificate_algorithmStringSignature Algorithm entered.The signature algorithm entered is invalid.
validityIntExpiry time of the entered certificate.Invalid certificate expiration time.
password_keyStringSensitive Information.Password for certificate key entered is invalid.
password_revocationStringSensitive Information.The certificate revocation password you entered is invalid.
environmentsArrayInformed Environments.
systemsArrayInformed Systems.
designStringDesign informed.
ip_externalStringIP entered.
ip_hostnameStringIP or hostname entered.
justificationStringInformed Justification.Justification must be a maximum of 1024 characters.
responsibleIntResponsible Code informed.The parental code you entered is invalid.
descriptionStringDescription entered.Description must be a maximum of 512 characters.

Query / List Request

GET https://vault_url/iso/certificate/request/list\[request_code\] 

The Query / List Request method queries one or more certificate requests on senhasegura .

Parameters

FieldTypeDescriptionRequired
code_requestIntCode of an already created Request.No
status requestIntCode of a status of a request.No
type_certificateIntType of certificate. The possible values are:
1 = DV SSL - Domain SSL;
2 = OV SSL - Organization SSL;
3 = EV SSL - Extended SSLNo
type_domainStringType of certificate domain. The possible values are:
SING = Single domain
MULT = Multiple domains
WILD = WildcardNo
organizationIntCode of the organization registered in senhasegura .No
common_nameStringCommon name of certificate.No
sanStringSubject Alternative Names, separated by commaNo
tagsStringCertificate ID tags, comma separatedNo
encryptionStringEncryption algorithm. The possible values are:
RSA, DSANo
encryption_key_sizeIntSize of encryption key. The possible values are:
4096, 2048, 1024No
algorithm_certifiedStringSignature algorithm. The possible values are:
SHA256, SHA384, SHA512No
validityIntCertificate validity time in days.No
password_keyStringCertificate key password.No
password_revocationStringCertificate revocation password.No
environmentsStringCertificate Environments, Comma SeparatedNo
systemsStringCertificate Systems, Comma SeparatedNo
designStringCertificate Design on request.No
ip_externalStringexternal certificate IP on request.No
ip_hostnameStringIP or certificate hostname on request.No
responsibleIntCode of the responsible for the request and the certificate.No
offsetIntBase number of record count by pagination.No
limitIntNumber of records in pagination.No

Response to certificate

If the method succeeds or fails, the response consists of a certified block with the fields:

FieldTypeSuccessError
status4xx
messageOKCould not find requests with the information provided
errorfalsetrue
code_requestIntRequest Code.There is no request with the given code. The request code you entered is invalid.
status_requestRequest status code and name.There are no requests with the status entered. The status code you entered is invalid.
type_certifiedIntType of certificate entered.There are no requests with the type of certificate entered. The certificate type you entered is invalid.
type_domainStringType of certificate domain entered.There are no requests with the domain type you entered. The certificate type domain you entered is invalid.
organizationIntOrganization code entered.There are no requests with the organization code entered. The organization code you entered is invalid.
common_nameStringCommon name entered.There are no requests with the given common name.
sanArraySAN informed.There are no requests with the informed SAN.
tagsArrayTags entered.There are no requests with the given Tag.
encryptionStringEncryption algorithm entered.There are no requests with the encryption algorithm entered. The encryption algorithm entered is invalid.
encryption_key_sizeIntEncryption key size entered.There are no requests with the encryption key size entered. The encryption key length you entered is invalid.
certified_algorithmStringSignature Algorithm entered.There are no requests with the signature algorithm entered. The signature algorithm you entered is invalid.
validityIntCertificate expiration time entered.There are no requests with the expiration date entered. Invalid certificate expiration time is invalid.
password_keyStringSensitive Information.There are no requests with the password of the entered key. The certificate key password you entered is invalid.
password_revocationStringSensitive Information.There are no requests with the revocation password entered. The certificate revocation password you entered is invalid.
environmentsArrayInformed environments.There are no requests with the informed environments.
systemsArrayInformed systems.There are no requests with the informed systems.
projectStringProject entered.There are no requests with the project entered.
ip_externalStringIP entered.No requests with external IP entered.
ip_hostnameStringIP or hostname entered.No requests with IP or hostname entered
justificationStringInformed Justification.
ResponsibleIntCode and name of the informed responsible.There are no requests with the informed responsible’s code.The responsable’s code you entered is invalid.
descriptionStringDescription entered.

Sign Request

GET https://vault_url/iso/certificate/request/sign\[request_code\] 

The Sign Request method signs an existing request on senhasegura .

Parameters

FieldTypeDescriptionRequired
code_requestIntCode of request to be signed.Yes
self_signedIntIndicates whether it is self-signed. The options will be:
1 = true, 0 = falseYes
caIntCA Code responsible for signing request. Required if self_signed is false.Conditional
justificationStringText up to 1024 characters for justification.No
reasonIntSubscription Reason Code. You should enter a reason code for a reason entered in senhasegura .Yes
itsm_codeStringcharacters to determine ITSM code. Required if in the certificate access group the parameter "Governance code required when justifying" is enabled. Perform ITSM validations in the same way as the web interface.Conditional

Response to certificate

If the method succeeds or fails, the response consists of a certified block with the fields:

FieldTypeSuccessError
status4xx
messageOKCould not sign request.
errorfalsetrue
code_requestIntRequest Code.Enter a request code.The request code you entered is invalid
self_signedIntValue entered.There are no requests for this entered self-signed value.The value for self-signed entered is invalid.
caIntCA code and CA name entered.There are no requests with the CA code entered. The CA code you entered is invalid.
justificationStringInformed Justification.Justification must be a maximum of 1024 characters
reasonIntReason code and name entered.Reason code entered is invalid.
ITSM codeStringITSM code entered.Enter the ITSM code.

Query / List Certificates

GET https://vault_url/iso/certificate/list/\[request_code\] 

The Query / List Certificates method queries one or more certificates in passwords.

Parameters

FieldTypeDescriptionRequired
code_ certificateIntCode of a certificate already created in passwords.No
status_certificateIntCode of a status of a certificate. The options will be:
1 = Valid
2 = Revoked
3 = Renewal pending
4 = ExpiredNo
activeIntCertificate Status on senhasegura . The options will be:
1 = Active, 0 = InactiveNo
start_validityStringExpiry start dateNo
end_validityStringExpiry dateNo
origin_certificateIntCertificate origin on senhasegura . The options will be:
SCAN = Scan and Discovery
REQU = Request
IMPO = Imported manuallyNo
type_certificateIntType of certificate. The options will be:
1 = DV SSL - Domain SSL
2 = OV SSL - Organization SSL
3 = EV SSL - Extended SSLNo
type_domainStringType of certificate domain. The options will be:
SING = Single domain
MULT = Multiple domains
WILD = WildcardNo
organizationIntOrganization code.No
common_nameStringCommon name of certificate.No
sanStringSubject Alternative Name. You may enter more than 1 separated by a comma.No
tagsStringCertificate ID Tags. You may enter more than 1 separed by comma.No
encryptionStringEncryption Algorithm. The options will be:
RSA, DSANo
encryption_key_sizeIntSize of encryption key. The options will be:
4096, 2048, 1024No
algorithm_certifiedStringSignature Algorithm The options will be:
sha256, sha384, sha512No
ValidityIntCertificate validity time in number of days.No
password_keyStringPassword of certificate key.No
password_revocationStringCertificate revocation password.No
EnvironmentsStringCertificate Environments. You may enter more than 1 separated by commas.No
SystemsStringCertificate Systems. You may enter more than 1 separated by commas.No
projectStringCertificate project on request.No
ip_externalStringexternal certificate IP on request.No
ip_hostnameStringIP or certificate hostname on request.No
self_signedIntIndicates whether it is self-signed. The options will be:
1 = true
0 = falseNo
caIntCA Code responsible for signing request.No
responsibleIntCode of the responsible for the request and the certificate.No
offsetIntBase number of record count by pagination.No
limitIntNumber of records in pagination.No

Response to certificates

If the method succeeds or fails, the response consists of a certified block with the fields:

FieldTypeSuccessError
status4xx
messageOKCould not sign request.
errorfalsetrue
code_requestIntRequest Code.Enter a request code.The request code you entered is invalid
status_certifiedIntCode and name of certificate statusThere are no certificates with the entered status. The status code you entered is invalid.
activeIntCode and name of the certificate status on senhaseguraThere is no certificate with the entered state. The state code you entered is invalid.
start_validityStringExpiry start dateThere are no certificates with the stated expiration date. The expiration start date you entered is invalid.
end_validityStringExpiry dateThere are no certificates with the stated expiration date. The expiration date entered is invalid.
origin_certificateIntCertificate origin in passwords secureThere are no certificates with the informed source. The source you entered is invalid.
type_certificateIntType of certificateThere are no certificates of the type entered. The certificate type you entered is invalid.
type_domainStringType of certificate domainThere are no certificates with the domain type you entered. The certificate type domain you entered is invalid.
organizationIntCode and name of the organization you enteredThere are no certificates with the organization code entered. The organization code you entered is invalid
common_nameStringCommon name of certificateThere are no certificates with the common name entered.
encryption_key_sizeIntSize of the certificate encryption keyThere are no certificates with the encryption key length entered. The encryption key length you entered is invalid.
algorithm_certifiedStringCertificate Signing AlgorithmThere are no certificates with the signature algorithm entered.The signature algorithm you entered is invalid.
validityIntCertificate validity timeThere are no certificates with the entered expiration time. Invalid certificate expiration time is invalid.
password_keyStringCertificate key password.There are no certificates with the entered key password. The certificate key password you entered is invalid.
password_revocationStringCertificate revocation password.There are no certificates with the revocation password entered. The certificate revocation password you entered is invalid.
EnvironmentsStringCertificate EnvironmentsThere are no certificates with the environment (s) entered.
systemsStringCertificate SystemsThere are no certificates with the system (s) entered.
projectStringCertificate Design. Eg project 1There are no certificates with the project informed.
ip_externalStringexternal certificate IP.No certificates with external IP entered.
ip_hostnameStringIP or certificate hostnameThere are no certificates with the given IP or hostname.
self_signedIntInfo if the certificate is self-signedNo certificates exist for this self-signed value entered. The value for self-signed entered is invalid.
caIntCA code and CA name enteredThere are no certificates with the CA code you entered. The CA code you entered is invalid.
ResponsibleIntCode and name of responsible person informedThere are no certificates with the responsible’s code entered. The responsible’s code you entered is invalid.
DescriptionDescription of the certificate
publish_infoAdditional information for publication
deviceDevices code attached with certificate

Functions

The senhasegura webservice has some functionality to perform operations on the application.

Publish Certificate

POST https://vault_url/iso/cert/publish 

Publish Certificate functionality prompts you to publish a certificate on one or more devices.

Parameters

FieldTypeDescriptionRequired
code_certificateIntCode of a certificate to be publish.Yes
code_profile_publicationIntPublish profile code.A publication profile previously registered on senhasegura will be used.Yes
justificationStringJustification of publication up to 1024 characters.No
reasonIntPublication reason code.You must enter a code for a reason entered on senhasegura .Yes
itms_codeStringcharacters to determine ITSM code.Required if in the certificate access group the parameter "Governance code required when justifying" is enabled. Perform ITSM validations in the same way as the web interface.Conditional
devicesArrayArray with the codes of the devices where the certificate is to be published
Devices must exist on senhasegura .Yes

Response to certificates

If the functions succeeds or fails, the response consists of a certified block with the fields:

FieldTypeSuccessError
status4xx
messageCreatedInvalid certificate code.
errorfalsetrue
code_publishingPosting scheduling code
reasonCode and name of reason for publicationReason code entered is invalid.
itms_codeStringITSM code enteredEnter the ITSM code. ITSM code does not exist on senhasegura integrated ITSM system. The code must be a maximum of 30 characters.
devicesArrayDevice Codes for Publishing

Query / List Publications

GET https://vault_url/iso/cert/publish/\[code_request\] 

The Query / List Publications feature queries one or more publications on senhasegura .

Parameters

FieldTypeDescriptionRequired
code_publicationIntPublication code.No
code_certifiedIntCode of certificate to be published.No
code_profile_publicationIntPublish Profile Code.No
creation_dateStringDate of registrationNo
processedIntPublication processing status.The options will be:
1 = Yes
0 = NoNo
errorIntPublication Error Status.The options will be:
1 = Yes
0 = NoNo
reasonIntPublication reason code.No
itms_codeStringITSM code Text reported.No
deviceIntDevice code of the publication.No
offsetIntBase number of record count by pagination.No
limitIntNumber of records in pagination.No

Response to certificates

If the function succeeds or fails, the response consists of a certified block with the fields:

FieldTypeSuccessError
status4xx
messageCreatedInvalid certificate code.
errorfalsetrue
code_publishingPosting scheduling code
reasonCode and name of reason for publicationReason code entered is invalid.
itms_codeStringITSM code enteredEnter the ITSM code. ITSM code does not exist on senhasegura integrated ITSM system. The code must be a maximum of 30 characters.
code_credentialPublishing credential codeThe credential code you entered is invalid.
usernameUsername for credential search
quantity_devicesNumber of devices in the publication

Create/Edit Apache Publication Profile

POST https://vault_url/iso/cert/profile/apache 

Create / Edit Apache Publishing Profile function creates or edits an Apache plugin publishing profile.

Parameters

FieldTypeDescriptionRequired
code_profileIntCode of an already created profile.If the code is not passed, the system will interpret it as creating a profile.No
name_profileStringName of profile to create.Yes
siteStringSite where the certificate is to be installed.
If not entered, the certificate will be installed on the default Apache site.No
config_pathStringAddress of the configuration.Standard:
/etc/apache2/sites-available/default.com.confNo
portIntPort.
Default:443No
code_credentialIntCredential code to be used in the publication. A credential previously registered in the vault will be used.This information is required if a username is not entered.Conditional
usernameStringUsername that will be used to find credentials for the publication.
This information is required if you do not enter a code_credentialConditional
devicesArrayArray with the codes of the devices where the certificate is to be publishedYes

Response to certificates

If the function succeeds or fails, the response consists of a certified block with the fields:

FieldTypeSuccessError
status- Created
200 - Edit4xx
messageCreatedInvalid certificate code.
errorfalsetrue
code_pathStringProfile nameThe code of profile informed is invalid
name_profileStringProfile name
siteStringInformed Text
config_pathStringConfigured Path
portIntPort
code_credentialIntCredential code to publicationThe credential code informed is invalid
usernameStringUsername to search credentials
devicesArrayDevices’ code to publication

Create/Edit IIS Publication Profile

POST https://vault_url/iso/cert/profile/iis 

Create/Edit IIS Publication Profile function creates or edits an Apache plugin publishing profile.

Parameters

FieldTypeDescriptionRequired
code_profileIntCode of an already created profile.If the code is not passed, the system will interpret it as creating a profile.No
name_profileStringName of profile to create.Yes
siteStringSite where the certificate is to be installed.
If not entered, the certificate will be installed on the default IIS site.No
cert_storeStringIIS certificate management repository.Default: MYNo
portIntPort.
Default:443No
code_credentialIntCredential code to be used in the publication. A credential previously registered in the vault will be used.This information is required if a username is not entered.Conditional
usernameStringUsername that will be used to find credentials for the publication.
This information is required if you do not enter a code_credentialConditional
devicesArrayArray with the codes of the devices where the certificate is to be publishedYes

Response to certificates

If the function succeeds or fails, the response consists of a certified block with the fields:

FieldTypeSuccessError
status- Created
200 - Edit4xx
messageCreatedInvalid certificate code.
errorfalsetrue
code_pathStringProfile nameThe code of profile informed is invalid
name_profileStringProfile name
siteStringInformed Text
cert_storeStringIIS certificate management repository
portIntPort
code_credentialIntCredential code to publicationThe credential code informed is invalid
usernameStringUsername to search credentials
devicesArrayDevices’ code to publication

Create/Edit F5 Big IP Publication Profile

POST https://vault_url/iso/cert/profile/bigip 

Create/Edit F5 Big IP Publication Profile function creates or edits an Apache plugin publishing profile.

Parameters

FieldTypeDescriptionRequired
code_profileIntCode of an already created profile.If the code is not passed, the system will interpret it as creating a profile.No
name_profileStringName of profile to create.Yes
name_partitionStringName of the partitionNo
name_certStringName of the certificate. If a certificate with the same name is already configured, on publication it will be replaced.No
profile_client_vipsArrayArray of SSL Client Profiles and their VIPsNo
profile_server_vipsArrayArray of SSL Server Profiles and their VIPsNo
code_credentialIntCredential code to be used in the publication. A credential previously registered in the vault will be used.This information is required if a username is not entered.Conditional
usernameStringUsername that will be used to find credentials for the publication.
This information is required if you do not enter a code_credentialConditional
devicesArrayArray with the codes of the devices where the certificate is to be publishedYes

Response to certificates

If the function succeeds or fails, the response consists of a certified block with the fields:

FieldTypeSuccessError
status- Created
200 - Edit4xx
messageCreatedInvalid certificate code
errorfalsetrue
code_profileIntPublish profile codeThe code of profile informed is invalid
name_profileStringProfile name
name_partitionStringName of the profile
name_certificateStringName of the certificate that is shown on the web application
profile_clientArrayComplete name of the profile
profile_serverArrayComplete name of the profile
code_credentialIntCredential code to publicationThe credential code informed is invalid
usernameStringUsername to search credentials
devicesArrayDevice’s code to publication

Create/Edit WebSphere WAS Profile Publication

POST https://vault_url/iso/cert/profile/was 

Create/Edit WebSphere WAS Profile Publication function creates or edits an Apache plugin publishing profile.

Parameters

FieldTypeDescriptionRequired
code_profileIntCode of an already created profile. If the code is not passed, the system will interpret it as creating a profile.No
name_profileStringName of profile to create.Yes
key_db_pathStringPath of the Key database nameYes
key_db_passwordStringServer’s passwordYes
labelStringServer’s labelYes
code_credentialIntCredential code to be used in the publication. A credential previously registered in the vault will be used.This information is required if a username is not entered.Conditional
usernameStringUsername that will be used to find credentials for the publication.
This information is required if you do not enter a code_credentialConditional
devicesArrayArray with the codes of the devices where the certificate is to be publishedYes

Response to certificates

FieldTypeSuccessError
status- Created
200 - Edit4xx
messageCreatedInvalid certificate code.
errorfalsetrue
code_profileIntPublish profile codeThe code of profile informed is invalid
name_profileStringProfile name
key_db_pathStringPath of the Key database name
labelStringServer’s label
code_credentialIntCredential code to publicationThe credential code informed is invalid
usernameStringUsername to search credentials
devicesArrayDevices’ code to publication