| --- |
| title: Using PKCS for Encrypted Authentication |
| --- |
| |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| |
| This section discusses the concepts and configurations for the sample UserPassword and PKCS implementations. Descriptions of their interfaces, classes, and methods are available in the API. |
| |
| **Note:** |
| Native client samples are provided in source form only in the "templates" directory within the product directory. |
| |
| With PKCS, clients send encrypted authentication credentials in the form of standard PKCS signatures to a <%=vars.product_name%> cache server when they connect to the server. The credentials consist of the alias name and digital signature created using the private key that is retrieved from the provided keystore. The server uses a corresponding public key to decrypt the credentials. If decryption is successful then the client is authenticated and it connects to the cache server. For unsuccessful decryption, the server sends an `AuthenticationFailedException` to the client, and the client connection to the cache server is closed. |
| |
| When clients require authentication to connect to a cache server, they use the `PKCSAuthInit` class implementing the `AuthInitialize` interface to obtain their credentials. For the PKCS sample provided by <%=vars.product_name%>, the credentials consist of an alias and an encrypted byte array. The private key is obtained from the PKCS\#12 keystore file. To accomplish this,` PKCSAuthInit` gets the alias retrieved from the `security-alias `property, and the keystore path from the `security-keystorepath` property. `PKCSAuthInit` also gets the password for the password-protected keystore file from the `security-keystorepass` property so the keystore can be opened. |
| |
| **The securityImpl Library** |
| |
| To use the PKCS sample implementation, you need to build OpenSSL and then build the securityImpl library. In the `geode.properties `file for the client, specify the `PKCSAuthInit` callback, the keystore path, the security alias, and the keystore password, like this: |
| |
| ``` pre |
| security-client-auth-library=securityImpl |
| security-client-auth-factory=createPKCSAuthInitInstance |
| security-keystorepath=<PKCS#12 keystore path> |
| security-alias=<alias> |
| security-keystorepass=<keystore password> |
| ``` |
| |
| For server side settings and PKCS configuration, see the server's security documentation. |
