CryptRetrieveObjectByUrlA 함수(wincrypt.h)
CryptRetrieveObjectByUrl 함수는 URL로 지정된 위치에서 PKI(공개 키 인프라) 개체를 검색합니다.
이러한 원격 개체는 인코딩된 형식이며 "컨텍스트" 형식으로 검색됩니다.
구문
BOOL CryptRetrieveObjectByUrlA(
[in] LPCSTR pszUrl,
[in] LPCSTR pszObjectOid,
[in] DWORD dwRetrievalFlags,
[in] DWORD dwTimeout,
[out] LPVOID *ppvObject,
[in] HCRYPTASYNC hAsyncRetrieve,
[in, optional] PCRYPT_CREDENTIALS pCredentials,
[in, optional] LPVOID pvVerify,
[in] PCRYPT_RETRIEVE_AUX_INFO pAuxInfo
);
매개 변수
[in] pszUrl
검색할 PKI 개체의 주소입니다. 지원되는 체계는 다음과 같습니다.
- ldap(Lightweight Directory Access Protocol)
- http
- https(CRL(인증서 해지 목록) 또는 OCSP(온라인 인증서 상태 프로토콜) 검색만 해당)
- 파일
[in] pszObjectOid
검색할 개체의 형식을 식별하는 null로 끝나는 ANSI 문자열의 주소입니다. 다음 값 중 하나일 수 있습니다.
| 값 | 의미 |
|---|---|
|
하나 이상의 데이터 BLOB을 검색합니다. 인코딩된 비트는 BLOB 배열로 반환됩니다. ppvObject 는 BLOB 배열을 수신하는 CRYPT_BLOB_ARRAY 구조체 포인터의 주소입니다. 이 구조체가 더 이상 필요하지 않은 경우 이 구조체의 주소를 CryptMemFree 함수에 전달하여 해제해야 합니다. |
|
하나 이상의 인증서를 검색합니다.
단일 개체를 검색하는 경우 ppvObject 는 컨텍스트를 수신하는 CERT_CONTEXT 구조체 포인터의 주소입니다. 이 컨텍스트가 더 이상 필요하지 않은 경우 CERT_CONTEXT 구조체 포인터를 CertFreeCertificateContext 함수에 전달하여 해제해야 합니다. 여러 개체를 검색하는 경우 ppvObject 는 인증서가 포함된 저장소의 핸들을 수신하는 HCERTSTORE 변수의 주소입니다. 이 저장소가 더 이상 필요하지 않은 경우 이 핸들을 CertCloseStore 함수에 전달하여 닫아야 합니다. |
|
하나 이상의 CRL(인증서 해지 목록 )을 검색합니다.
단일 개체를 검색하는 경우 ppvObject 는 컨텍스트를 수신하는 CRL_CONTEXT 구조체 포인터의 주소입니다. 이 컨텍스트가 더 이상 필요하지 않은 경우 CRL_CONTEXT 구조체 포인터를 CertFreeCRLContext 함수에 전달하여 해제해야 합니다. 여러 개체를 검색하는 경우 ppvObject 는 CRL이 포함된 저장소의 핸들을 수신하는 HCERTSTORE 변수의 주소입니다. 이 저장소가 더 이상 필요하지 않은 경우 이 핸들을 CertCloseStore 함수에 전달하여 닫아야 합니다. |
|
하나 이상의 CTL(인증서 신뢰 목록 )을 검색합니다.
단일 개체를 검색하는 경우 ppvObject 는 컨텍스트를 수신하는 CTL_CONTEXT 구조체 포인터의 주소입니다. 이 컨텍스트가 더 이상 필요하지 않은 경우 CTL_CONTEXT 구조체 포인터를 CertFreeCTLContext 함수에 전달하여 해제해야 합니다. 여러 개체를 검색하는 경우 ppvObject 는 CTL이 포함된 저장소의 핸들을 수신하는 HCERTSTORE 변수의 주소입니다. 이 저장소가 더 이상 필요하지 않은 경우 이 핸들을 CertCloseStore 함수에 전달하여 닫아야 합니다. |
|
ppvObject 는 메시지에서 개체를 포함하는 저장소의 핸들을 수신하는 HCERTSTORE 변수의 주소입니다. 이 저장소가 더 이상 필요하지 않은 경우 이 핸들을 CertCloseStore 함수에 전달하여 닫아야 합니다. |
|
ppvObject 는 개체가 포함된 저장소의 핸들을 수신하는 HCERTSTORE 변수의 주소입니다. 이 저장소가 더 이상 필요하지 않은 경우 이 핸들을 CertCloseStore 함수에 전달하여 닫아야 합니다. |
|
ppvObject 는 CRYPT_BLOB_ARRAY 구조체에 대한 포인터의 주소입니다. |
[in] dwRetrievalFlags
유선 URL에서 검색된 캐시된 URL 또는 URL을 사용할지 여부를 결정합니다. 개체가 반환되는 양식은 pszObjectOid 값에 따라 결정됩니다.
| 값 | 의미 |
|---|---|
|
캐시에 URL을 쓰기 전에 유선 URL로 검색된 콘텐츠의 유효성을 검사합니다.
기본 공급자는 AIA 검색에 대한 HTTPS 프로토콜을 지원하지 않습니다. |
|
이 값은 지원되지 않습니다. |
|
URL 캐시에서만 인코딩된 비트를 검색합니다. 유선을 사용하여 URL을 검색하지 마세요. |
|
검색된 인코딩된 비트를 URL 캐시에 저장하지 않습니다. 이 플래그를 설정하지 않으면 검색된 URL이 캐시됩니다. |
|
HTTP 검색에 대한 기본 GET 메서드 대신 POST 메서드를 사용합니다.
POST URL에서 추가 이진 데이터 및 헤더 문자열은 다음 형식으로 기본 URL에 추가됩니다. BaseURL/OptionalURLEscaped&Base64EncodedAdditionalData?OptionalAdditionalHTTPHeaders 다음 예제에서는 마지막 슬래시 표시(/)로 구분된 추가 이진 데이터와 기본 URL에 추가된 물음표(?)로 구분된 Content-Type 헤더를 보여 줍니다.
이 플래그가 설정되면 CryptRetrieveObjectByUrl 함수는 마지막 슬래시 표시(/) 및 물음표(?) 구분 기호를 사용하여 URL을 구문 분석합니다. 슬래시 표시(/)로 구분된 문자열에는 이스케이프 문자 또는 이스케이프 시퀀스가 없는 일반 텍스트 URL과 WinHttpSendRequest 함수에 lpOptional 매개 변수로 전달되기 전에 이진 형식으로 디코딩된 Base64 데이터가 포함됩니다. 물음표(?)로 구분된 문자열은 WinHttpSendRequest 함수에 pwszHeaders 매개 변수로 전달됩니다. |
|
제공된 호스트 문자열에서 A 레코드 전용 DNS 조회를 수행하여 호스트 이름을 확인할 때 거짓 DNS 쿼리가 생성되지 않도록 합니다. 이 플래그는 도메인 이름이 아닌 호스트 이름을 전달할 때 사용해야 합니다. |
|
각 LDAP 개체의 항목 인덱스 및 특성 이름을 검색합니다. 반환된 각 BLOB의 시작 부분에는 다음 ANSI 문자열이 포함됩니다. "decimal\0특성 이름\0의 항목 인덱스" 이 플래그가 설정되면 BLOB이 반환되도록 pszObjectOid 는 NULL 이어야 합니다. 이 플래그는 ldap 체계에만 적용됩니다. |
|
LDAP 검색 scope URL의 기본으로 설정되지 않은 경우 실패합니다. LDAP에만 사용합니다. |
|
Kerberos 인증 프로토콜을 사용하여 서버 간 모든 LDAP 트래픽을 디지털 서명합니다. 이 기능은 일부 애플리케이션에 필요한 무결성을 제공합니다. |
|
자동 인증 처리를 금지합니다. |
|
조건부 HTTP URL 검색을 사용하도록 설정합니다. 이 플래그가 설정되면 HTTP_STATUS_NOT_MODIFIED 반환하는 조건부 검색의 경우 CryptRetrieveObjectByUrl 은 TRUE 를 반환하고 ppvObject 는 NULL로 설정됩니다. pAuxInfo가 NULL이 아니면 dwHttpStatusCode가 HTTP_STATUS_NOT_MODIFIED 설정됩니다. 그렇지 않으면 성공적인 검색을 위해 ppvObject 가 업데이트됩니다. |
|
후속 검색 시 유선에 충돌하기 전에 오프라인 오류 및 지연을 추적합니다. 이 값은 와이어 검색 전용입니다. |
|
개체의 프록시 캐시 검색을 사용하도록 설정합니다. 프록시 캐시가 명시적으로 바이패스되지 않은 경우 fProxyCacheRetrieval은 pAuxInfo에서 TRUE로 설정됩니다. 이 값은 HTTP URL 검색에만 적용됩니다. |
|
사용 가능한 경우 여러 개체를 검색합니다. OID(개체 식별자) 값이 CONTEXT_OID_CAPI2_ANY 않는 한 모든 개체는 pszObjectOid 값에 의해 결정된 것과 같은 유형의 개체여야 합니다. |
|
URL에 캐시에서 플러시되지 않도록 태그를 지정합니다. 자세한 내용은 INTERNET_CACHE_ENTRY_INFO STICKY_CACHE_ENTRY 참조하세요. |
|
만든 컨텍스트에서 서명 확인을 획득합니다. 이 경우 pszObjectOid 는 NULL 이 아니어야 하며 pvVerify 는 서명자 인증서 컨텍스트를 가리킵니다. |
|
이 플래그는 구현되지 않습니다. 이 메서드를 사용하지 마십시오. |
|
와이어에서만 인코딩된 비트를 검색합니다. URL 캐시를 사용하지 않습니다. |
[in] dwTimeout
검색 대기할 최대 시간(밀리초)을 지정합니다. 값이 0으로 지정된 경우 이 함수는 시간 초과되지 않습니다. URL 구성표가 file:/// 경우 이 매개 변수는 사용되지 않습니다.
[out] ppvObject
반환된 개체에 대한 포인터의 주소입니다. 반환 형식은 pszObjectOid에 표시된 지원되는 형식 중 하나일 수 있습니다.
[in] hAsyncRetrieve
이 매개 변수는 예약되어 있으며 NULL로 설정해야 합니다.
[in, optional] pCredentials
이 매개 변수는 사용되지 않습니다.
[in, optional] pvVerify
확인 개체에 대한 포인터입니다. 이 개체는 dwRetrievalFlags 매개 변수의 함수입니다. dwRetrievalFlags가 CRYPT_VERIFY_CONTEXT_SIGNATURE 경우 호출자가 서명자의 인증서 컨텍스트 또는 인덱스를 가져오는 데 관심이 없음을 나타내는 것은 NULL일 수 있습니다.
[in] pAuxInfo
CRYPT_RETRIEVE_AUX_INFO 구조체에 대한 선택적 포인터입니다. NULL이 아니고 구조체의 cbSize 멤버가 설정된 경우 이 매개 변수는 마지막으로 성공한 와이어 검색 시간을 반환합니다.
반환 값
함수가 성공하면 반환 값은 0이 아닌 값(TRUE)입니다.
함수가 실패하면 반환 값은 0(FALSE)입니다.
설명
원격 개체 검색 관리자는 두 공급자 모델을 노출합니다. 하나는 URL 스키마, 즉 ldap, http, ftp 또는 파일에 정의된 대로 설치 가능한 프로토콜 공급자를 허용하는 스키마 공급자 모델입니다. 스키마 공급자 진입점은 CryptRetrieveObjectByUrl 함수와 동일합니다. 그러나 반환되는 *ppvObject 는 항상 인코딩된 비트의 계산된 배열입니다(검색된 개체당 하나).
두 번째 공급자 모델은 검색된 인코딩된 비트에 따라 컨텍스트 핸들(개체)의 설치 가능한 작성자를 허용하는 컨텍스트 공급자 모델입니다. CryptRetrieveObjectByUrl 호출에 지정된 OID(개체 식별자)를 기반으로 디스패치됩니다.
인증서, 트러스트 목록, 해지 목록, PKCS #7 메시지 및 여러 동종 개체와 같은 개별 PKI 개체를 검색할 수 있습니다. WINDOWS Vista SP1(서비스 팩 1) 및 Windows Server 2008부터 "http:" 및 "ldap:" 검색 보안이 강화되었습니다. 이 함수는 새로 정의된 스키마뿐만 아니라 "http:" 및 "ldap:" URL 스키마를 지원합니다.
Windows XP: 네트워크 검색에는 "ftp:"가 지원되지 않습니다.
참고
wincrypt.h 헤더는 CRYptRetrieveObjectByUrl을 유니코드 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택하는 별칭으로 정의합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입에 대한 규칙을 참조하세요.
요구 사항
| 지원되는 최소 클라이언트 | Windows XP [데스크톱 앱만 해당] |
| 지원되는 최소 서버 | Windows Server 2003 [데스크톱 앱만 해당] |
| 대상 플랫폼 | Windows |
| 헤더 | wincrypt.h |
| 라이브러리 | Cryptnet.lib |
| DLL | Cryptnet.dll |
추가 정보
피드백
출시 예정: 2024년 내내 콘텐츠에 대한 피드백 메커니즘으로 GitHub 문제를 단계적으로 폐지하고 이를 새로운 피드백 시스템으로 바꿀 예정입니다. 자세한 내용은 다음을 참조하세요. https://aka.ms/ContentUserFeedback
다음에 대한 사용자 의견 제출 및 보기