Software Version 4.5. SSL Web Service API Release Date: 12 th May, InCommon c/o Internet Oakbrook Drive, Suite 300 Ann Arbor MI, 48104

Transcription

1 Software Version 4.5 SSL Web Service API Release Date: 12 th May, 2014 InCommon c/o Internet Oakbrook Drive, Suite 300 Ann Arbor MI, 48104

2 Table of Contents Version History Introduction Remote Functions Function for SSL Certificate Renewal Arguments Return value 'status code' of operation Function for Collecting Renewed SSL Certificate Arguments Return value SSLRenewResponse Function for SSL Certificate Enrollment Arguments AuthData type Server Type Return value 'status code' of operation Function for Checking if Certificate is Available Arguments Return value status of certificate availability Function for Collecting Enrolled SSL Certificate Arguments Return value SSLCollectResponse SSL type Function for SSL Certificate Revocation Arguments Return value 'status code' of operation Function for loading list of available certificate types for customer Arguments Return value CustomerCertType type for saving information about available customer certificate type Utility Function for Getting Short Information about Web Service (name, version, etc.)...13 InCommon Certificate Manager SSL Web Service API 18-July

3 Version History 1.1. Removed extra error codes. 1. Initial Version 1.2. Added 'SSL' type with 'renewid' field. The 'SSLCollectReponse' type contains 'SSL' field now Fixed variable's name Added 'Invalid ID' return code with 'getcollectstatus' method. 1 Introduction Name : EPKIManagerSSLService Service EPR : View WSDL : Service : The Service allows the Administrator to renew and collect renewed SSL certificates, request, collect, and revoke SSL certificates. 2 Remote Functions 2.1 Function for SSL Certificate Renewal int renew(string renewid) Arguments Variable Name Type Max. Length renewid String 20 Given by cm in notification letter when SSL certificate was issued Return value 'status code' of operation Status code If 'status code' < 0-3 = internal error; -4 = invalid renewid. If 'status code' = 0 0 = success. InCommon Certificate Manager SSL Web Service API 18-July

4 2.2 Function for Collecting Renewed SSL Certificate SSLRenewResponse collectrenewed(string renewid, int formattype) Arguments Variable Name Type Max. Length renewid String 20 Given by cm in notification letter when SSL certificate was issued. formattype int 1 0 = X509 PEM Bundle; 1 = X509 PEM Certificate only; Format of SSL to be returned. 2 = X509 PEM Intermidiate certificate only; 3 = PKCS#7 PEM Bundle; 4 = PKCS#7 DER Bundle Return value SSLRenewResponse SSLRenewResponse - Object that contains collect operation status and SSL Certificate in Byte array if succeed. Method Name Possible value(s) int geterrorcode() 0 = issued; -1 = applied; -2 = certificate error, invalid state; -3 = internal error; -4 = SSL Certificate not exists; -5 = waiting for approval by admin; -6 = admin has declined request. byte[] getdata() If status code = 0, then certificate in the form of byte array if succeed, null otherwise. InCommon Certificate Manager SSL Web Service API 18-July

5 2.3 Function for SSL Certificate Enrollment Integer enroll(authdata data, Integer orgid, String secretkey, String csr, String phrase,string subjaltnames, CustomerCertType certtype, Integer numberservers, Integer servertype, Integer term, String comments) Arguments Variable Name Type Max. Length authdata AuthData Authentication data for access. See section AuthData Type. orgid Integer Organization identifier. Can be obtained from Admin UI 'Settings' - 'Organization' tab. secretkey String 20 Secret Key for SSL is setting in Client Admin UI. 'Settings' 'Organization' 'Add/Edit Organization' dialog, 'SSL' tab. csr String Subject: The fields may be in any order (although multiple street addresses, if present, should be in the correct order). Algorithm OID = rsaencryption (PKCS#1). Size = 512 to 8192 bits. Certificate Signing Request (Base-64 encoded with or without the -----BEGIN xxxxx----- and -----END xxxxx----- header and footer) Attributes: Any attributes MAY be present, but will be ignored if the subject_ fields are used. Signature Algorithm: md5withrsaencryption (PKCS#1) InCommon Certificate Manager SSL Web Service API 18-July

6 Variable Name Type Max. Length phrase String 64 Pass phrase for revocation. subjaltnames String Subject Alternative Names splitted with ",". List of Subject Alternative Names. certtype CustomerC erttype Certificate types available for the ordering customer. See description in section for more details. numberservers Integer Number of servers. servertype Integer Server type of the SSL certificate. See description below in section Server Type. term Integer Term in years. Term of the SSL certificate. comments String 256 The message that will be attached to the certificate AuthData type Method Name setlogin(string value) Set login name for account within cm. This is the login of the Admin with role 'MRAO Admin, RAO SSL Admin' or 'DRAO SSL Admin' within cm account. setpassword(string value) Set password for account within cm. This is the login of the Admin with role 'MRAO Admin, RAO SSL Admin' or 'DRAO SSL Admin' within cm account. seturi(string value) URI for logging into account within cm Server Type Server Type 1 AOL 2 Apache/ModSSL InCommon Certificate Manager SSL Web Service API 18-July

7 Server Type 3 Apache-SSL (Ben-SSL, not Stronghold) 4 C2Net Stronghold 33 Cisco 3000 Series VPN Concentrator 34 Citrix 5 Cobalt Raq 6 Covalent Server Software 7 IBM HTTP Server 8 IBM Internet Connection Server 9 iplanet 10 Java Web Server (Javasoft / Sun) 11 Lotus Domino 12 Lotus Domino Go! 13 Microsoft IIS 1.x to 4.x 14 Microsoft IIS 5.x and later 15 Netscape Enterprise Server 16 Netscape FastTrack 17 Novell Web Server 18 Oracle 19 Quid Pro Quo 20 R3 SSL Server 21 Raven SSL 22 RedHat Linux 23 SAP Web Application Server InCommon Certificate Manager SSL Web Service API 18-July

8 Server Type 24 Tomcat 25 Website Professional 26 WebStar 4.x and later 27 WebTen (from Tenon) 28 Zeus Web Server 29 Ensim 30 Plesk 31 WHM/cPanel 32 H-Sphere -1 OTHER Return value 'status code' of operation Status code If 'status code' < 0-3 = The 'User name' argument is invalid. -7 = Country is not a valid ISO-3166 country! -9 = The CSR is not valid Base-64 data! -10 = The CSR cannot be decoded! -11 = The CSR uses an unsupported algorithm! -12 = The CSR has an invalid signature! -13 = The CSR uses an unsupported key size! -14 = An unknown error occurred! -16 = Permission denied! -31 = The is not a valid = The passphrase is empty! InCommon Certificate Manager SSL Web Service API 18-July

9 Status code -33 = The certificate type is invalid! -34 = The secret key is invalid! -35 = The server type is invalid! -36 = The term is invalid for customer type! -37 = -Cert type name is not valid = Invalid auth data! = The 'Access code' argument is invalid = Customer configuration is not allowed the desired action 2.4 Function for Checking if Certificate is Available Integer getcollectstatus(authdata data, Integer id) Arguments Variable Type Max. Length Name authdata AuthData Authentication data for access. See section AuthData Type. id Integer Any SSL identifier previously returned to your account. This is the SSL identifier previously returned by function enroll Return value status of certificate availability 0 = Cert is being processed by Comodo 1 = Cert is available for collection -14 = An unknown error occurred! -16 = Permission denied! -23 = The certificate hasn't been approved yet! InCommon Certificate Manager SSL Web Service API 18-July

10 - 40 = Invalid ID = Invalid authentication data for customer -101 = Invalid authentication data for customer organization -110 = Domain is not allowed for customer -111 = Domain is not allowed for customer organization = Customer configuration is not allowed the requested action 2.5 Function for Collecting Enrolled SSL Certificate SSLCollectResponse collect(authdata data, Integer id, int formattype) Arguments Variable Name Type Max. Length authdata AuthData Authentication data for access. See section AuthData Type. id Integer Any SSL identifier previously returned to your account. This is the SSL identifier previously returned by function enroll. formattype int 1 0 = X509 PEM Bundle; 1 = X509 PEM Certificate only; Allowed formats for downloading of SSL. 2 = X509 PEM Intermidiate certificate only; 3 = PKCS#7 PEM Bundle; 4 = PKCS#7 DER Bundle Return value SSLCollectResponse SSLCollectResponse - Object that contains collect operation status and SSL Certificate in Base-64 if succeed. InCommon Certificate Manager SSL Web Service API 18-July

11 Method Name int getstatuscode() 0 = when certificate is not ready -14 = An unknown error occurred! -16 = Permission denied! -20 = CSR rejected -21 = The certificate has been revoked! -22 = Still awaiting payment! - 40 = Invalid ID = Invalid auth data! = Customer configuration is not allowed the desired action SSL type Method Name String getrenewid() Given by cm when SSL certificate was issued. This code may be used for renewing the certificate. String getcertificate() The certificate in Base Function for SSL Certificate Revocation Integer revoke(authdata data, Integer id, String reason) Arguments Variable Name Type Max. Length authdata AuthData Authentication data for access. See section AuthData Type. id Integer Any SSL identifier previously returned to your account. This is the SSL identifier previously returned by function enroll. reason String 256 Revocation reason for audit logging. Empty String InCommon Certificate Manager SSL Web Service API 18-July

12 Variable Name Type Max. Length allowed Return value 'status code' of operation -14 = An unknown error occurred! -16 = Permission denied! - 40 = Invalid ID = Invalid auth data! = Customer configuration is not allowed the desired action 2.7 Function for loading list of available certificate types for customer. CustomerCertTypeResponse getcustomercerttypes(authdata data) Arguments Variable Name Type Max. Length authdata AuthData Authentication data for access. See section AuthData Type Return value. CustomerCertTypeResponse - Object that contains array available customer certificate types (see description of CustomerCertType below). Field Name int getstatuscode() -14 = An unknown error occurred! -16 = Permission denied! = Invalid auth data! = Customer configuration is not allowed the desired action InCommon Certificate Manager SSL Web Service API 18-July

13 CustomerCertType type for saving information about available customer certificate type. Variable Name int getid() The service customer cert type identifier. String getname() Name of this certificate type. For example InstantSSL int[] getterms List of available terms for this customer certificate type. 2.8 Utility Function for Getting Short Information about Web Service (name, version, etc.). String getwebserviceinfo() InCommon Certificate Manager SSL Web Service API 18-July