# Obtain a signature credential of a user

# Alias

`CscCredentialsInfo`

# Description

Obtains a signature credential (i.e., a signing identity) of a user.

# Request

To obtain a signature credential of a user, the client application must send the following request to the TRIDENT using TLS.

`POST /trustedx-resources/csc/v2/credentials/info`
Important

[CSC_STANDARD_V2] requires that the base path of all requests of the access API to a remote signature services provider be `/csc/v2/`. Thus, if the TRIDENT administrator decides to follow the standard strictly, they must deploy the system so that the base path of the request is `/csc/v2` instead of`/trustedx-resources/csc/v2`. To determine if this is the case in your situation, check the "`oauth2`" property of the JSON object provided by the Obtain information on the CSC signature service operation.

## Content-Type Header

`Content-Type: application/json`

## Request Parameters

Name | Type | Usage | Description
`credentialID` | String | Required | Identifier of the signature credential to be obtained.
`certificates` | String | Optional | Indication whether either the certificate that forms part of the credential ("`single`"), the complete certificate chain of the certificate ("`chain`") or neither of these ("`none`") is to be returned in the response. I.e.: "`none`": no certificate. "`single`": user's signing certificate. "`chain`": user's signing certificate and the complete certificate chain. The default value is "`single`".
`certInfo` | Boolean | Optional | Indication whether information on the certificate that forms part of the credential is to be returned in the response. This information may be useful if the signature application needs information on the certificate but does not want to have to decode it. The default value is `false`.

## Authorization

The request must contain a bearer access token with the `service` scope. As a rule, obtaining this token via either an authorization code grant or client credentials grant OAuth 2.0 flow is possible. When the token is obtained through an OAuth 2.0 Authorization Code Grant, the user whose credentials list is requested is implicit in the token, so the `userID` request parameter should not be used.

The access token must be put in the `Authorization` header, as explained in RFC 6750. I.e., as follows:

`Authorization: Bearer <token>`

# Response

## Status-Line

If the request is successfully processed, the HTTP response contains the following `Status-Line`:

`HTTP/1.1 200 OK`

## Content-Type Header

`Content-Type: application/json;charset=UTF-8`

## Body

JSON object that contains the information of a signature credential .

`{`
`"description": {string},`
`"signatureQualifier": {string},`
`"key": {`
`"status": {string},`
`"algo": [{string}],`
`"len": {number}`
`},`
`"cert": {`
`"status": {string},`
`"certificates": [{string}],`
`"issuerDN": {string},`
`"serialNumber": {string},`
`"subjectDN": {string},`
`"validFrom": {string},`
`"validTo": {string}`
`},`
`"authMode": {string},`
`"SCAL": {string},`
`"multisign": {number},`
`"lang": {string}`
`}`

Property | Type | Description
`description` | String | Descriptive text (in the language specified in the `lang` property and limited to 255 characters) of the signature credential provided.
`signatureQualifier` | String | This property is only present if the "`signatureQualifier`" parameter was present in the credentials authorization request to obtain the `credentialID.` Identifier qualifying the type of signature for which this credential is suitable. The only value supported is `"eu_eidas_qes"`, and it means that the signing key associated with the credential is suitable for qualified electronic signatures as per the EU eIDAS regulation.
`key/status` | String | Status of the signing key associated with the signature credential: `"enabled``"`: the signing key is enabled and can be used to generate signatures. `"disabled``"`: the signing key is disabled and cannot be used to generate signatures.
`key/algo` | String Array | List of OIDs of the signature algorithms that can be used with the signing key associated with the signature credential. The elements of the list can be one or more of the following: "`1.2.840.113549.1.1.1`": RSA encryption "`1.2.840.113549.1.1.11`": sha256WithRSAEncryption "`1.2.840.113549.1.1.12`": sha384WithRSAEncryption "`1.2.840.113549.1.1.13`": sha512WithRSAEncryption "`1.2.840.10045.4.3.2`": sha 256WithECDSA " `1.2.840.10045.4.3.3`": sha384 WithECDSA " `1.2.840.10045.4.3.4`": sha512 WithECDSA
`key/curve` | String | OIDs de la c urvas elíptica de la clave de firma asociada a la credencial de firma. "`1.2.840.10045.3.1.7`": secp256r1 " `1.3.132.0.34`": secp384r1 "`1.3.132.0.35`": secp512r1
`key/len` | Number | Size in bytes of the signing key associated with the signature credential.
`cert/status` | String | Status of the signing certificate that forms part of the signature credential: "`valid`": the signing certificate is valid. "`expired`": the signing certificate has expired.
`cert/certificates` | String Array | This property is only present if the value of the "`certificates`" parameter of the request is "`single`" or "`chain`" "`single`": `cert/certificates` contains the signing certificate that forms part of the signature credential (encoded in base64). "`chain`": `cert/certificates` contains the signing certificate that forms part of the signature credential (encoded in base64) and its complete certificate chain (with the certificates of this chain encoded in base64).
`cert/issuerDN` | String | This property is only present if the value of the "`certInfo`" parameter is true and contains the DN of the issuer (Issuer Distinguished Name) of the signing certificate that forms part of the signature credential.
`cert/serialNumber` | String | This property is only present if the value of the "`certInfo`" parameter is `true` and contains the serial number (Serial Number) of the signing certificate that forms part of the signature credential.
`cert/SubjectDN` | String | This property is only present if the value of the "`certInfo`" parameter is true and contains the DN of the subject (Subject Distinguished Name) of the signing certificate that forms part of the signature credential.
`cert/ValidFrom` | String | This property is only present if the value of the "`certInfo`" parameter is `true` and contains the start time of the validity period of the signing certificate that forms part of the signature credential with the `YYYYMMDDHHMMSSZ` format.
`cert/ValidTo` | String | This property is only present if the value of the "`certInfo`" parameter is true and contains the end time of the validity period of the signing certificate that forms part of the signature credential, with the `YYYYMMDDHHMMSSZ` format.
`authmode` | String | Mode for obtaining authorization from the user for using the signing key associated with the signature credential to generate a signature. Always has "`oauth2code`" as value, i.e., an Authorization Code Grant OAuth 2.0 flow must be performed, and a token with the `credential` scope must be obtained.
`SCAL` | String | Level that must be achieved to demonstrate exclusive control (by the user) of the signing key associated to the signature credential to be able to generate signatures with it (see [EN 419 241-1] ) : 1: SCAL1 level is required: signatures generated with the signing key will be advanced electronic signatures. 2: SCAL2 level is required: signatures generated with the signing key will be qualified electronic signatures.
`multisign` | Number | The maximum number of signatures that one user's authorization allows generating with the signing key associated with the signature credential (see also the `numSignatures` parameter in Obtain an OAuth 2.0 authorization).
`lang` | String | Language used in the response (in the `description` property). This will be the value specified by an administrator in the settings of the CSC service. The language is specified as per [RFC 5646].

# Error Management

If the request does not contain the `Authorization: Bearer` header, the TRIDENT returns an HTTP response with the 401 Unauthorized `Status Code`.

If the request is not successfully processed, the TRIDENT returns an HTTP error response with the `Content-Type: application/json;charset=utf-8` header and a JSON object in the body with the following properties:

- `error`: Error code.

- `error_description`: Additional description of the error. Not required.

Error case | Status Code (HTTP) | error | error_description
The `credentialID` parameter was not included in the request, or its value is not a String. | 400 Bad Request | `invalid_request` | `invalidParameter`
The `credentialID` parameter of the request is invalid. | 400 Bad Request | `invalid_request` | `invalidCredentialId`
The `certificates` parameter of the request is invalid. | 400 Bad Request | `invalid_request` | `invalidParameter`

# Example

## Request

The signature application requests the signature credential identified by "GX0112348". For this, it sends the following request to the TRIDENT specifying in it that it wants to receive information on the signing certificate along with the certificate:

`POST /trustedx-resources/csc/v2/credentials/info HTTP/1.1`
`Host: rse.corporation.com`
`Authorization: Bearer 9ade1210b7ac648b49defc577aa258eb2701b2064a14de13842524c2fd59c597`
`Content-Type: application/json`
`{`
`"credentialID": "GX0112348",`
`"certificates": "single",`
`"certInfo": true`
`}`

## Response

The TRIDENT responds to the signature application providing it with the signature credential requested.

`HTTP/1.1 200 OK`
`Content-Type: application/json;charset=UTF-8`
`{`
`"description": "Corporative signature credential",`
`"key": {`
`"status": "enabled",`
`"algo": [`
`"1.2.840.113549.1.1.13",`
`"1.2.840.113549.1.1.1",`
`"1.2.840.113549.1.1.11",`
`"1.2.840.113549.1.1.12"`
`],`
`"len": 2048`
`},`
`"cert": {`
`"certificates": ["MIIFpTCCBI2...m1SEW"],`
`"serialNumber": "67210661094051074244364068313147966416",`
`"validFrom": "20210120121230Z",`
`"validTo": "20220120121230Z",`
`"issuerDN": "CN=Entrust QA (SML) Class 3 Client CA - SHA256, OU=\"(c) 2015 Entrust, Inc. - for authorized use only\",`
`OU=See www.entrust.net/legal-terms, O=\"Entrust, Inc.\", C=US",`
`"subjectDN": "CN=John Doe, O=Corporation, L=Otwaw, ST=Ontario, C=CA"`
`},`
`"authMode": "oauth2code",`
`"multisign": 40,`
`"lang": "en-US",`
`"SCAL": "2"`
`}`