diff options
Diffstat (limited to 'lib/public_key/doc/src/public_key.xml')
| -rw-r--r-- | lib/public_key/doc/src/public_key.xml | 317 |
1 files changed, 317 insertions, 0 deletions
diff --git a/lib/public_key/doc/src/public_key.xml b/lib/public_key/doc/src/public_key.xml new file mode 100644 index 0000000000..dc9a96906f --- /dev/null +++ b/lib/public_key/doc/src/public_key.xml @@ -0,0 +1,317 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> + <header> + <copyright> + <year>2008</year> + <year>2008</year> + <holder>Ericsson AB, All Rights Reserved</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + The Initial Developer of the Original Code is Ericsson AB. + </legalnotice> + + <title>public_key</title> + <prepared>Ingela Anderton Andin</prepared> + <responsible></responsible> + <docno></docno> + <date></date> + <rev></rev> + </header> + <module>public_key</module> + <modulesummary> API module for public key infrastructure.</modulesummary> + <description> + <p>This module provides functions to handle public key infrastructure + from RFC 3280 - X.509 certificates (will later be upgraded to RFC 5280) + and some parts of the PKCS-standard. + Currently this application is mainly used by the new + ssl implementation. The API is yet under construction + and only a few of the functions are currently documented and thereby supported. + </p> + </description> + + <section> + <title>COMMON DATA TYPES </title> + + <note><p>All records used in this manual + <!-- except #policy_tree_node{} --> + are generated from asn1 specifications + and are documented in the User's Guide. See <seealso + marker="public_key_records">Public key records</seealso> and <seealso + marker="cert_records">X.509 Certificate records</seealso>. + </p></note> + + <p>Use the following include directive to get access to the + records and constant macros described here and in the User's Guide.</p> + + <code> -include_lib("public_key/include/public_key.hrl"). </code> + + <p><em>Data Types </em></p> + + <p><c>boolean() = true | false</c></p> + + <p><c>string = [bytes()]</c></p> + + <p><c>asn1_der_encoded() = binary() | [bytes()]</c></p> + + <p><c>der_bin() = binary() </c></p> + + <p><c>oid() - a tuple of integers + as generated by the asn1 compiler.</c></p> + + <p><c>public_key() = rsa_public_key() | dsa_public_key()</c></p> + + <p><c>rsa_public_key() = #'RSAPublicKey'{}</c></p> + + <p><c>rsa_private_key() = #'RSAPrivateKey'{} </c></p> + + <p><c>dsa_public_key() = integer() </c></p> + + <p><c>public_key_params() = dsa_key_params() </c></p> + + <p><c>dsa_key_params() = #'Dss-Parms'{} </c></p> + + <p><c>private_key() = rsa_private_key() | dsa_private_key()</c></p> + + <p><c>rsa_private_key() = #'RSAPrivateKey'{} </c></p> + + <p><c>dsa_private_key() = #'DSAPrivateKey'{}</c></p> + + <p><c>x509_certificate() = "#Certificate{}"</c></p> + + <p><c>x509_tbs_certificate() = #'TBSCertificate'{} </c></p> + +<!-- <p><c>policy_tree() = [Root, Children]</c></p> --> + +<!-- <p><c>Root = #policy_tree_node{}</c></p> --> + +<!-- <p><c>Children = [] | policy_tree()</c></p> --> + +<!-- <p> The policy_tree_node record has the following fields:</p> --> + +<!-- <taglist> --> + +<!-- <tag>valid_policy</tag> --> +<!-- <item> Is a single policy OID representing a --> +<!-- valid policy for the path of length x.</item> --> + +<!-- <tag>qualifier_set</tag> --> +<!-- <item>A set of policy qualifiers associated --> +<!-- with the valid policy in certificate x.</item> --> + +<!-- <tag>critically_indicator</tag> --> +<!-- <item>The critically_indicator indicates whether the --> +<!-- certificate policy extension in certificate x was marked as --> +<!-- critical. </item> --> + +<!-- <tag>expected_policy_set</tag> --> +<!-- <item>The expected_policy_set contains one or more policy OIDs --> +<!-- that would satisfy this policy in the certificate x+1. </item> --> +<!-- </taglist> --> + </section> + +<funcs> + <func> + <name>decode_private_key(KeyInfo) -> </name> + <name>decode_private_key(KeyInfo, Password) -> {ok, PrivateKey} | {error, Reason}</name> + <fsummary> Decodes an asn1 der encoded private key.</fsummary> + <type> + <v> KeyInfo = {KeyType, der_bin(), ChipherInfo} </v> + <d> As returned from pem_to_der/1 for private keys</d> + <v> KeyType = rsa_private_key | dsa_private_key </v> + <v> ChipherInfo = opaque() | no_encryption </v> + <d> ChipherInfo may contain encryption parameters if the private key is password + protected, these are opaque to the user just pass the value returned by pem_to_der/1 + to this function.</d> + <v> Password = string() </v> + <d>Must be specified if CipherInfo =/= no_encryption</d> + <v> PrivateKey = private_key() </v> + <v> Reason = term() </v> + </type> + <desc> + <p>Decodes an asn1 der encoded private key.</p> + </desc> + </func> + + <func> + <name>pem_to_der(File) -> {ok, [Entry]}</name> + <fsummary>Reads a PEM file and translates it into its asn1 der + encoded parts.</fsummary> + <type> + <v>File = path()</v> + <v>Password = string()</v> + <v>Entry = {entry_type(), der_bin(), CipherInfo}</v> + <v> ChipherInfo = opaque() | no_encryption </v> + <d> ChipherInfo may contain encryption parameters if the private key is password + protected, these will be handled by the function decode_private_key/2. </d> + <v>entry_type() = cert | cert_req | rsa_private_key | dsa_private_key | + dh_params </v> + </type> + <desc> + <p>Reads a PEM file and translates it into its asn1 der + encoded parts.</p> + </desc> + </func> + + <func> + <name>pkix_decode_cert(Cert, Type) -> {ok, DecodedCert} | {error, Reason}</name> + <fsummary> Decodes an asn1 der encoded pkix certificate. </fsummary> + <type> + <v>Cert = asn1_der_encoded() </v> + <v>Type = plain | otp</v> + <v>DecodeCert = x509_certificate() </v> + <d>When type is specified as otp the asn1 spec OTP-PKIX.asn1 is used to decode known + extensions and enhance the signature field in + #'Certificate'{} and '#TBSCertificate'{}. This is currently used by the new ssl + implementation but not documented and supported for the public_key application.</d> + <v>Reason = term() </v> + </type> + <desc> + <p> Decodes an asn1 encoded pkix certificate.</p> + </desc> + </func> + +<!-- <func> --> +<!-- <name> pkix_encode_cert(Cert) -> {ok, EncodedCert} | {error, Reason}</name> --> +<!-- <fsummary>Encodes a certificate record using asn1. </fsummary> --> +<!-- <type> --> +<!-- <v>Cert = x509_certificate() </v> --> +<!-- <v>EncodedCert = asn1_der_encoded() </v> --> +<!-- <v>Reason = term() </v> --> +<!-- </type> --> +<!-- <desc> --> +<!-- <p> Encodes a certificate record using asn1.</p> --> +<!-- </desc> --> +<!-- </func> --> + +<!-- <func> --> +<!-- <name>pkix_path_validation(TrustedCert, CertChain, Options) -> {ok, Result} | {error, Reason}</name> --> + +<!-- <fsummary>Performs a basic path validation according to RFC 3280</fsummary> --> +<!-- <type> --> +<!-- <v>TrustedCert = asn1_der_encoded()</v> --> +<!-- <v>CertChain = [asn1_der_encoded()]</v> --> +<!-- <v>Options = [{Option, Value}]</v> --> +<!-- <v>Result = {{algorithm(), public_key(), --> +<!-- public_key_params()}, policy_tree()}</v> --> +<!-- </type> --> + +<!-- <desc> --> +<!-- <p>Available options are: </p> --> +<!-- <taglist> --> +<!-- <tag>{validate_extension_fun, fun()}</tag> --> +<!-- <item> A fun behaving according to the following outline: --> +<!-- <code> --> +<!-- [...] --> +<!-- ValidateExtensionFun = fun(Extensions, UserState) -> --> +<!-- validate_extensions(Extensions, UserState, []) --> +<!-- end, --> +<!-- [...] --> + +<!-- validate_extensions([], UserState, UnknowExtension) -> --> +<!-- {UserState, UnknowExtension}; --> +<!-- validate_extensions([#'Extension'{} = Ext | Rest], UserState, UnknowExtension) -> --> +<!-- case valid_extension(Ext) of --> +<!-- {true, NewUserState} -> --> +<!-- validate_extensions(Rest, NewUserState, UnknowExtension); --> +<!-- unknown -> --> +<!-- validate_extensions(Rest, UserState, [Ext | UnknowExtension]); --> +<!-- {false, Reason} -> --> +<!-- throw(bad_cert, Reason) --> +<!-- end. --> +<!-- </code> --> + +<!-- </item> --> + +<!-- <tag>{policy_set, [oid()]}</tag> --> +<!-- <item>A set of certificate policy --> +<!-- identifiers naming the policies that are acceptable to the --> +<!-- certificate user. If the user is not concerned about --> +<!-- certificate policy there is no need --> +<!-- to set this option. Defaults to the --> +<!-- special value [?anyPolicy]. --> +<!-- </item> --> + +<!-- <tag>{policy_mapping, boolean()}</tag> --> +<!-- <item>Indicates if policy --> +<!-- mapping, initially, is allowed in the certification path. --> +<!-- Defaults to false. --> +<!-- </item> --> + +<!-- <tag> {explicit_policy, boolean()}</tag> --> +<!-- <item>Indicates if the path, initially, must be --> +<!-- valid for at least one of the certificate policies in the user --> +<!-- specified policy set. --> +<!-- Defaults to false. --> +<!-- </item> --> + +<!-- <tag>{inhibit_any_policy, boolean()}</tag> --> +<!-- <item>Indicates whether the anyPolicy OID, initially, should --> +<!-- be processed if it is included in a certificate. --> +<!-- Defaults to false. --> +<!-- </item> --> + +<!-- </taglist> --> + +<!-- <p>Performs a basic path validation according to RFC 3280, --> +<!-- e.i. signature validation, time validation, issuer validation, --> +<!-- alternative subject name validation, CRL validation, policy --> +<!-- validation and checks that no unknown extensions --> +<!-- are marked as critical. The option <c>validate_extension_fun</c> --> +<!-- may be used to validate application specific extensions. If --> +<!-- a validation criteria is found to be invalid the validation process --> +<!-- will immediately be stopped and this functions will return --> +<!-- {error, Reason}. --> +<!-- </p> --> +<!-- </desc> --> +<!-- </func> --> + +<!-- <func> --> +<!-- <name>sign(DigestOrTBSCert, Key) -> </name> --> +<!-- <name>sign(DigestOrTBSCert, Key, KeyParams) -> {ok, SignatureOrDerCert} | {error, Reason}</name> --> +<!-- <fsummary>Signs Digest/Certificate using Key.</fsummary> --> +<!-- <type> --> +<!-- <v>DigestOrTBSCert = binary() | x509_tbs_certificate()</v> --> +<!-- <v>Key = private_key()</v> --> +<!-- <v>SignatureORDerCert = binary() | der_bin() </v> --> +<!-- <v>Reason = term() </v> --> +<!-- </type> --> +<!-- <desc> --> +<!-- <p> Signs Digest/Certificate using Key, in the later --> +<!-- case a der encoded x509_certificate() will be returned. </p> --> +<!-- </desc> --> +<!-- </func> --> + +<!-- <func> --> +<!-- <name>verify_signature(Digest, Signature, Key) -> </name> --> +<!-- <name>verify_signature(DerCert, Key, KeyParams) -> </name> --> +<!-- <name>verify_signature(Digest, Signature, Key, Params) -> Verified </name> --> +<!-- <fsummary> Verifies the signature. </fsummary> --> +<!-- <type> --> +<!-- <v>Digest = binary() </v> --> +<!-- <v>DerCert = der_bin() </v> --> +<!-- <v>Signature = binary() </v> --> +<!-- <v>Key = public_key() </v> --> +<!-- <v>Params = key_params()</v> --> +<!-- <v>Verified = boolean()</v> --> +<!-- </type> --> +<!-- <desc> --> +<!-- <p> Verifies the signature Signature. If the key is an rsa-key no --> +<!-- paramters are neeed.</p> --> +<!-- </desc> --> +<!-- </func> --> +</funcs> + +</erlref> |