Ckbk ORTHOpride web service Versin v1 This dcument is prvided t yu free f charge by the ehealth platfrm Willebrekkaai 38 38, Quai de Willebrek 1000 BRUSSELS All are free t circulate this dcument with reference t the URL surce.
Table f cntents Table f cntents...2 1. Dcument management...3 1.1 Dcument histry...3 2. Intrductin...4 2.1 Gal f the service...4 2.2 Gal f the dcument...4 2.3 ehealth dcument references...4 2.4 External dcument references...4 3. Business and privacy requirements...5 3.1 Certificates...5 3.2 ehealth cntact...5 4. Glbal verview...6 5. Step-by-step...7 5.1 Technical requirements...7 5.1.1 Use f the ehealth SSO slutin...7 5.1.2 Encryptin...8 5.1.3 Security plicies t apply...8 5.2 Prcess verview...8 5.3 Web service...9 5.3.1 sendcmsmessage...9 6. Risks and security...11 6.1 Security...11 6.1.1 Business security...11 6.1.2 Web service...11 7. Test prcedure...12 7.1 Request a test case...12 7.2 Request a hspital certificate...12 8. Errr and failure messages...13 T the attentin f: IT expert willing t integrate this web service. ehealth-orthopride web service v.1-23.12.2014 2/13
1. Dcument management 1.1 Dcument histry Versin Date Authr Descriptin f changes / remarks 1 11/12/2014 ehealth First revisin ehealth-orthopride v.1 23.12.2014 3/13
2. Intrductin 2.1 Gal f the service The ORTHOpride web service allws surgens authrized t place r remve rthpaedic implants t register hip and knee prsthesis thrugh a dedicated hspital system. 2.2 Gal f the dcument This dcument is nt a develpment r prgramming guide fr internal applicatins. Instead it prvides functinal and technical infrmatin and allws an rganizatin t integrate and use the ehealth service. But in rder t interact in a smth, hmgeneus and risk cntrlled way with a maximum f partners, ehealth partners must cmmit t cmply with the requirements f specificatins, data frmat and release prcesses described in this dcument. Technical and business requirements must be met in rder t allw the integratin and validatin f the ehealth service in the client applicatin. 2.3 ehealth dcument references All the dcument references can be fund in the technical library n the ehealth prtal 1. These versins r any fllwing versins can be used fr the ehealth service. ID Title Versin Date Authr 1 Glssary.pdf pm ehealth 2 ehealth STS 1.1 31/08/2010 ehealth 3 Ckbk bekende bestemmeling/destinataire cnnu 2.3 06/05/2011 ehealth 2.4 External dcument references All dcuments can be fund thrugh the internet. They are available t the public, but nt supprted by ehealth. ID Title Surce Date Authr 1 OASIS SAML Tken Prfile http://www.asispen.rg/cmmittees/d wnlad.php/16768/ws sv1.1-spec-s- SAMLTkenPrfile.pdf 01/02/2006 OASIS 1 www.ehealth.fgv.be ehealth-orthopride v.1 23.12.2014 4/13
3. Business and privacy requirements 3.1 Certificates An ehealth certificate is used t identify the initiatr f the request. If yu dn t have ne, see: Dutch versin: https://www.ehealth.fgv.be/nl/supprt/basisdiensten/ehealth-certificaten French versin: https://www.ehealth.fgv.be/fr/supprt/services-de-base/certificats-ehealth 3.2 ehealth cntact ehealth CntactCenter: 02 / 788 51 55 r via mail n supprt@ehealth.fgv.be Fr users in prductin please cntact Dutch versin https://www.ehealth.fgv.be/nl/neem-cntact-met-de-penbare-instelling-ehealth-platfrm French versin https://www.ehealth.fgv.be/fr/cntactez-institutin-publique-plate-frme-ehealth Fr users in acceptatin, please cntact inf@ehealth.fgv.be ehealth-orthopride v.1 23.12.2014 5/13
4. Glbal verview The first step is t request a SAML tken frm ur STS service. See 5.1.1 fr mre details. After receiving a valid tken, an ETK is needed fr the encryptin f the business message. This ETK is retrieved frm ur ETK dept. See 5.1.2 fr mre details. The next step is t create the business message (see the ckbk prvided by ecare inside ecare ORTHOpride WS.zip ), encrypt it using the ETK and calling the WS ORTHOpride pipe. This request and the respnse are described inerrr! Reference surce nt fund.. ehealth-orthopride v.1 23.12.2014 6/13
5. Step-by-step 5.1 Technical requirements 5.1.1 Use f the ehealth SSO slutin The cmplete verview f the prfile and a step-by-step implementatin t start prtecting a new applicatin with SSO @ ehealth is described in the ehealth STS ckbk. In rder t implement a call t the ehealth STS yu can reuse the implementatin as prvided in the "ehealth technical cnnectr": - https://www.ehealth.fgv.be/fr/supprt/cnnectrs - https://www.ehealth.fgv.be/nl/supprt/cnnectrs Nevertheless, ehealth implementatins use standards and any ther cmpatible technlgy (web service stack fr the client implementatin) can be used instead. The attributes that need t be prvided and the attributes that shuld be certified by ehealth in rder t btain a tken valid fr ecare ORTHOpride services are described in sectins 5.1.1.1 and 5.1.1.2. T access the ecare ORTHOpride web services, the respnse tken must cntain true fr all f the certificatin attributes. If yu btain false, cntact ehealth t verify that the requested test cases were crrectly cnfigured. 5.1.1.1 Orthpedist within a hspital The SAML tken request is secured with the ehealth certificate f the hspital. The certificate used by the Hlder-Of-Key verificatin mechanism is the same ehealth certificate. The needed attributes are the fllwing (AttributeNamespace: "urn:be:fgv:identificatin-namespace"): The scial security identificatin number f the rthpedist: urn:be:fgv:persn:ssin The NIHII number f the hspital: urn:be:fgv:ehealth:1.0:certificatehlder:hspital:nihii-number and urn:be:fgv:ehealth:1.0:hspital:nihii-number Yu must als specify which infrmatin must be asserted by ehealth: The scial security identificatin number f the dctr (AttributeNamespace: "urn:be:fgv:identificatin-namespace"): urn:be:fgv:persn:ssin The NIHII number f the hspital (AttributeNamespace: "urn:be:fgv:identificatin-namespace"): urn:be:fgv:ehealth:1.0:certificatehlder:hspital:nihii-number and urn:be:fgv:ehealth:1.0:hspital:nihii-number the hspital must be a recgnized hspital (AttributeNamespace: urn:be:fgv:certifiednamespace:ehealth) urn:be:fgv:ehealth:1.0:certificatehlder:hspital:nihiinumber:recgnisedhspital:blean Additinally, ehealth will use the scial security identificatin number, as certified by ehealth, t verify the NIHII number f the persn and t verify that the persn is a recgnized rthpedist. 5.1.1.2 Surgen within a hspital The SAML tken is the same as discussed abve, but additinally ehealth will use the scial security identificatin number, as certified by ehealth, t verify the NIHII number f the persn and t verify that the persn is a recgnized surgen. ehealth-orthopride v.1 23.12.2014 7/13
5.1.2 Encryptin The business part f the message t send t the web service must be encrypted. T encrypt the message, yu shuld retrieve the public key n the ETK (ehealth Tken Key) dept. And then, encrypt the message using this public key via ehealth encryptin libraries. All the infrmatin abut the use f the encryptin libraries and the call t the ETK (ehealth Tken Key) dept are described in the ckbks available n the ehealth technical library n the ehealth website ( Ckbk bekende bestemmeling / Ckbk destinataire cnnu ). The table belw prvides yu the identifiers t use in the GetEtkRequest. Envirnment Type Value Applicatin ID Acceptance Envirnment CBE 0206653946 ECAREACC Prductin Envirnment CBE 0206653946 ECAREPRD Mre infrmatin can be fund in the ckbk dcuments prvided by ecare (cntained in the "ecare Orthpride WS.zip" archive). 5.1.3 Security plicies t apply We expect that yu use SSL ne way fr the transprt layer. As web service security plicy, we expect: A timestamp (the date f the request), with a Time t live f ne minute (if the message desn t arrive during this minute, he shall nt be treated). The signature with the certificate f the timestamp, (the ne mentined abve) the bdy (the message itself) and the binary security tken: a SAML tken issued by STS This will allw ehealth t verify the integrity f the message and the identity f the message authr. A dcument explaining hw t implement this security plicy can be btained by ehealth. The STS ckbk can be fund n the ehealth prtal, Technical Library. 5.2 Prcess verview Summary: T call the ecare Orthpride web service: Add the encrypted business message t the SendCMSMessageRequest element (base64). See sectin 5.3. Add t the SOAP header the fllwing elements: SAML Tken: The SAML Assertin received frm the ehealth STS. This Assertin needs t be frwarded exactly as received in rder t nt t break the signature f the ehealth STS. The tken needs t be added accrdingly t the specificatins f the OASIS SAML Tken Prfile (hlder-f-key). Timestamp. ehealth-orthopride v.1 23.12.2014 8/13
A signature that has been placed n the SOAPBdy with the certificate f which the public key is mentined in the SAML Assertin. The signature element (mentined abve) needs t cntain: SignedInf with References t the sapbdy. KeyInf with a SecurityTkenReference pinting t the SAML Assertin. See als the WSSP in the WSDL 2. As fr nw, nly the peratins described belw are available. The peratins fr the web services are: sendecaredeclaratin updateecaredeclaratin deleteecaredeclaratin The endpints and service cntract (ehealth XSDs) fr each f these peratins can be fund in the Registry n the ehealth prtal, sectin Supprt - Tls. Fr mre details, see the ckbk dcuments as prvided by ecare (cntained in the "ecare Orthpride WS.zip" archive). 5.3 Web service 5.3.1 sendcmsmessage This methd is used t send the encrypted ecare business message t the ecare platfrm thrugh ehealth. 5.3.1.1 Request The input request is defined by a tag which will cntain the encrypted request in base64. Fr mre details, see the ckbk dcuments as prvided by ecare (cntained in the "ecare Orthpride WS.zip" archive). 5.3.1.2 Respnse There are different pssible types f respnse: If there are n technical errrs, respnses as described in the remainder f this sectin are returned. If a technical errr ccurs, see chapter 8. Fr mre details n the specific elements and the cncepts behind them, see the ckbk dcuments as prvided by ecare (cntained in the "ecare Orthpride WS.zip" archive). 2 WSDL's can be fund in the ehealth Service Registry: https://services.ehealth.fgv.be/registry/uddi/bsc/web r https://services-acpt.ehealth.fgv.be/registry/uddi/bsc/web fr services in the acceptance envirnment. ehealth-orthopride v.1 23.12.2014 9/13
The utput respnse is defined by a tag which will cntain the encrypted respnse prvided by the ecare ORTHOpride web service. Fr mre details and hw t decrypt, see the ckbk dcuments as prvided by ecare (cntained in the "ecare Orthpride WS.zip" archive). ehealth-orthopride v.1 23.12.2014 10/13
6. Risks and security 6.1 Security 6.1.1 Business security In case the develpment adds an additinal use case based n an existing integratin, ehealth must be infrmed at least ne mnth in advance with a detailed estimate f the expected lad. This will ensure an effective capacity management. In case f technical issues n the web service, the partner may btain supprt frm the cntact center. In case ehealth finds a bug r vulnerability in its sftware, the partner is advised t update his applicatin with the newest versin f the sftware within 10 business days. In case the partner finds a bug r vulnerability in the sftware r web service that ehealth delivered, he is bliged t cntact and infrm ehealth immediately and he is nt allwed t publish this bug r vulnerability in any case. 6.1.2 Web service Web service security used in this manner is in accrdance with the cmmn standards. Yur call will prvide: SSL ne way Time-t-live f the message: ne minute. Signature f the timestamp, bdy and binary security tken. This will allw ehealth t verify the integrity f the message and the identity f the message authr. N encryptin n the message (nly the business part is encrypted). ehealth-orthopride v.1 23.12.2014 11/13
7. Test prcedure This chapter explains the prcedures fr testing ORTHOpride WS in acceptatin r prductin. 7.1 Request a test case T be authrized t call the web services, the hspital must be cnfigured in the ehealth acceptance envirnment. S, fill in the excel file that is cntained in the "Ecare_ Orthpride web services.zip" archive and send it t inf@ehealth.fgv.be After the cnfiguratin is dne, a certificate shuld be requested fr this hspital. 7.2 Request a hspital certificate The develped functinality needs t be tested using an acceptance certificate fr hspital. Therefre a participating test-hspital must first have a certificate-respnsible. Acceptance tests need t be perfrmed nsite (in a pilt hspital). Therefre, the hspital-acceptance certificate is required. Sftware cmpanies may nly cnduct acceptance tests in the acceptance envirnment f the hspital where the acceptance certificate and key pair f the specific envirnment shall be cnsulted n the predefined path ( Hme Directry under: \ehealth\keystre\ as set ut in ehealth Certifcate Manager manual 2.1.12). ehealth-orthopride v.1 23.12.2014 12/13
8. Errr and failure messages There are different pssible types f respnse: If there are n technical errrs, respnses as described in sectin 5.3 are returned. In the case f a technical errr, a SOAP fault exceptin is returned (see table belw) If an errr ccurs, first please verify yur request. Fllwing table cntains a list f cmmn system errr cdes fr the ehealth Service Bus. Descriptin f the pssible SOAP fault exceptins. Errr cde Cmpnent Descriptin Slutin/Explanatin SOA-00001 Unknwn Service errr This is the default errr sent t the cnsumer in case n mre details are knwn. SOA-01001 Cnsumer Service call nt authenticated SOA-01002 Cnsumer Service call nt authrized SOA-02001 Prvider Service nt available. Please cntact service desk SOA-02002 Prvider Service temprarily nt available. Please try later Frm the security infrmatin prvided, r the cnsumer culd nt be identified r the credentials prvided are nt crrect The cnsumer is identified and authenticated, but is nt allwed t call the given service. An unexpected errr has ccurred Retries will nt wrk Service desk may help with rt cause analysis An unexpected errr has ccurred Retries shuld wrk If the prblem persists service desk may help SOA-03001 Cnsumer Malfrmed message This is a default errr fr cntent related errrs in case n mre details are knwn. SOA-03002 Cnsumer Message must be SOAP Message des nt respect the SOAP standard SOA-03003 Cnsumer Message must cntain SOAP bdy Message respects the SOAP standard, but bdy is missing SOA-03004 Cnsumer WS-I cmpliance failure Message des nt respect the WS-I standard SOA-03005 Cnsumer WSDL cmpliance failure Message is nt cmpliant with WSDL in Registry/Repsitry SOA-03006 Cnsumer XSD cmpliance failure Message is nt cmpliant with XSD in Registry/Repsitry SOA-03007 Cnsumer Message cntent validatin failure Frm the message cntent (cnfrm XSD): Extended checks n the element frmat failed Crss-checks between fields failed ehealth-orthopride v.1 23.12.2014 13/13